Is it easy or difficult to use our developer documentation? Let us know in this short survey ↗

On this page

WebFinger

The purpose of the WebFinger interface is to allow a client application to determine the Identity Provider that a given username (or identifier) should be routed to based on your organization's Identity Provider Routing Rules (IdP Discovery Policy). For an introduction to the topic, see IdP Discovery.

The endpoint is: https://${yourOktaDomain}/.well-known/webfinger

This is a public, unprotected interface that can be queried without supplying an SSWS token.

Finding a User's IdP

GET /.well-known/webfinger

Fetch the IdP to be used for a particular user. You must supply a resource query parameter.

Request Parameters

The table below summarizes the supported query parameters:

Parameter Description Param Type DataType Required
resource User's login value prefixed with okta:acct: URL String TRUE
rel Allows you to limit the result to certain IdPs URL Array FALSE

Note: Valid values for rel are http://openid.net/specs/connect/1.0/issuer and okta:idp, the first value being an Okta org, and the second being any configurable IdP.

Request Example

curl -v -X GET \
-H "Accept: application/jrd+json" \
-H "Content-Type: application/json" \
"https://${yourOktaDomain}/.well-known/webfinger?resource=okta:acct:joe.stormtrooper%40example.com"

Response Example

In this example, there is a rule configured that has a user identifier condition which says that users with the domain example.com should be routed to a configured SAML IdP:

{
    "subject": "okta:acct:joe.stormtrooper@example.com",
    "links": [
        {
            "rel": "okta:idp",
            "href": "https://{yourOktaDomain}/sso/idps/0oas562BigqDJl70T0g3",
            "titles": {
                "und": "MySamlIdp"
            },
            "properties": {
                "okta:idp:metadata": "https://{yourOktaDomain}/api/v1/idps/0oas562BigqDJl70T0g3/metadata.xml",
                "okta:idp:type": "SAML2",
                "okta:idp:id": "0oas562BigqDJl70T0g3"
            }
        }
    ]
}

Request Example

curl -v -X GET \
-H "Accept: application/jrd+json" \
-H "Content-Type: application/json" \
"https://${yourOktaDomain}/.well-known/webfinger?resource=okta:acct:joe.stormtrooper%example.com&rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer"

Note: This request looks similar to the previous one, but it includes a rel parameter that limits the results to a particular set of IdPs.

Response Example

In this example, there is already a rule configured that has a user identifier condition which says that users with the domain example.com should be routed to a configured SAML IdP. However, we supplied a rel parameter of http://openid.net/specs/connect/1.0/issuer that limited the result to Okta:

{
    "subject": "okta:acct:joe.stormtrooper@example.com",
    "links": [
        {
            "rel": "https://openid.net/specs/connect/1.0/issuer",
            "href": "https://{yourOktaDomain}/sso/idps/OKTA",
            "titles": {
                "und": "{subdomain}"
            },
            "properties": {
                "okta:idp:type": "OKTA"
            }
        }
    ]
}