Interacting with IDP APIs Paige Freeman May 15, 2023 19:58 Updated OpenID Connect & OAuth 2.0 API IDP is a standards-compliant OAuth 2.0 authorization server. OpenID Connect extends OAuth 2.0. The OAuth 2.0 protocol provides API security via scoped access tokens, and OpenID Connect provides user authentication and single sign-on (SSO) functionality. This page contains detailed information about the OAuth 2.0 and OpenID Connect endpoints that IDP exposes on its authorization servers. Endpoints Endpoint Use /authorize Interact with the resource owner and obtain an authorization grant. /token Obtain an access and/or ID token by presenting an authorization grant or refresh token. /introspect Return information about a token. /revocation Revoke an access or refresh token. /endsession End the session associated with the given ID token. /.well-known/openid-configuration/jwks Return public keys used to sign responses. /userinfo Return claims about the authenticated end user. /.well-known/openid-configuration Return OpenID Connect metadata related to the specified authorization server. Composing your base URL All of the endpoints on this page start with an authorization server, however the URL for that server varies depending on the endpoint and the type of authorization server. You have two types of authorization servers to choose from depending on your use case: Single Sign-On to IDP This is for the use case where your users are all part of your IDP organization, and you would just like to offer them single sign-on (for example, you want your employees to sign in to an application with their IDP accounts). In OAuth 2.0 terminology, IDP is both the authorization server and the resource server. When IDP is serving as the authorization server for itself, we refer to this as the "IDP Org Authorization Server" and your base URL looks like this: https://${IDPDomain}/${OrganizationTenant} The full URL to the /authorize endpoint looks like this: https://${IDPDomain}/${OrganizationTenant}/authorize /authorize GET ${baseUrl}/authorize This is a starting point for browser-based OpenID Connect flows such as the implicit and authorization code flows. This request authenticates the user and returns tokens along with an authorization grant to the client application as a part of the callback response. When making requests to the /authorize endpoint, the browser (user agent) should be redirected to the endpoint. You can't use AJAX with this endpoint. Request Query Parameters Parameter Description Required client_id Obtained during manual client registration. TRUE code_challenge A challenge for PKCE. The challenge is verified in the access token request. FALSE code_challenge_method Method used to derive the code challenge for PKCE. Valid value: S256 FALSE login_hint A username to prepopulate if prompting for authentication. FALSE max_age Allowable elapsed time, in seconds, since the last time the end user was actively authenticated by IDP. FALSE nonce A value that is returned in the ID token. It is used to mitigate replay attacks. TRUE prompt Valid values: none, consent, login, or consent and login in either order. See Parameter details for more information. FALSE redirect_uri Callback location where the authorization code or tokens should be sent. It must match the value preregistered in IDP during client registration. TRUE response_type Any combination of code, token, and id_token. The combination determines the flow. TRUE response_mode How the authorization response should be returned. Valid values: fragment, form_post, query or IDP_post_message. If id_token or token is specified as the response type, then query isn't allowed as a response mode. Defaults to fragment in implicit and hybrid flows. FALSE scope openid is required for authentication requests. Other scopes may also be included. TRUE state A value to be returned in the token. The client application can use it to remember the state of its interaction with the end user at the time of the authentication call. It can contain alphanumeric, comma, period, underscore, and hyphen characters. See Parameter details. TRUE Parameter details idp, sessionToken and idp_scope are IDP extensions to the OpenID specification. All other parameters comply with the OpenID Connect specification and their behavior is consistent with the specification. prompt: If no prompt parameter is specified, the standard behavior occurs: If an IDP session already exists, the user is silently authenticated. Otherwise, the user is prompted to authenticate. If scopes are requested that require consent and consent isn't yet given by the authenticated user, the user is prompted to give consent. There are four possible values for this parameter: none: Don't prompt for authentication or consent. If an IDP session already exists, the user is silently authenticated. Otherwise, an error is returned. login: Always prompt the user for authentication, regardless of whether they have an IDP session. consent: Depending on the values set for consent_method in the app and consent on the scope, display the IDP consent dialog, even if the user has already given consent. User consent is available for Custom Authorization Servers (requires the API Access Management feature and the User Consent feature enabled). login consent or consent login (order doesn't matter): The user is always prompted for authentication, and the user consent dialog appears depending on the values set for consent_method in the app and consent on the scope, even if the user has already given consent. request: IDP validates the request parameter in the following ways: iss is required and must be the client_id. aud is required and must be the same value as the Authorization Server issuer that mints the ID or access token. This value is published in the metadata for your Authorization Server. JWT lifetime is evaluated using the iat and exp claims, if present. If the JWT is expired or not yet valid, IDP returns an invalid_request_object error. IDP rejects JWTs that expire more than one hour in the future. response_mode: Each value for response_mode delivers different behavior: query - Parameters are encoded in the query string added to the redirect_uri when redirecting back to the client. form_post - Parameters are encoded as HTML form values (application/x-www-form-urlencoded format) and are transmitted via the HTTP POST method to the client. state: IDP requires the OAuth 2.0 state parameter on all requests to the /authorize endpoint to prevent cross-site request forgery (CSRF). The OAuth 2.0 specification requires that clients protect their redirect URIs against CSRF by sending a value in the authorize request that binds the request to the user-agent's authenticated state. Using the state parameter is also a countermeasure to several other known attacks as outlined in OAuth 2.0 Threat Model and Security Considerations. postMessage() data object Use the postMessage() data object to help you when working with the IDP_post_message value of the response_mode request parameter. message: Parameter Description DataType access_token An access token. This is returned if the response_type included token. String error The error code, if something went wrong. String error_description Additional error information (if any). String id_token An ID token. This is returned if the response_type included id_token. String state The unmodified state value from the request. String The IDP-post-message response mode always uses the origin from the redirect_uri specified by the client. This is crucial to prevent the sensitive token data from being exposed to a malicious site. Response properties Irrespective of the response type, the contents of the response are as described in the table. Property Description DataType access_token An access token. This is returned if response_type included token. String code An opaque value that can be used to redeem tokens from the token endpoint. code is returned if the response_type includes code. The code has a lifetime of 300 seconds. String error The error code, if something went wrong. String error_description Additional error information (if any). String expires_in Number of seconds until the access_token expires. This is only returned if the response included an access_token. String id_token An ID token. This is returned if the response_type included id_token. String scope Scopes specified in the access_token. Returned only if the response includes an access_token. String state The unmodified state value from the request. String token_type The token type is always Bearer and is returned only when token is specified as a response_type. String Possible errors These APIs are compliant with the OpenID Connect and OAuth 2.0 spec with some IDP specific extensions. OAuth 2.0 spec error codes Error Id Details access_denied The server denied the request. invalid_client The specified client ID is invalid. invalid_grant The specified grant is invalid, expired, revoked, or doesn't match the redirect URI used in the authorization request. invalid_request The request is missing a necessary parameter, the parameter has an invalid value, or the request contains duplicate parameters. invalid_scope The scopes list contains an invalid or unsupported value. invalid_token The provided access token is invalid. server_error The server encountered an internal error. temporarily_unavailable The server is temporarily unavailable, but should be able to process the request at a later time. unsupported_response_type The specified response type is invalid or unsupported. unsupported_response_mode The specified response mode is invalid or unsupported. This error is also thrown for disallowed response modes. For example, if the query response mode is specified for a response type that includes id_token. OpenID Connect spec error codes Error Id Details insufficient_scope The access token provided doesn't contain the necessary scopes to access the resource. login_required The request specified that no prompt should be shown but the user is currently not authenticated. Request examples This request initiates the authorization code flow as signaled by response_type=code. The request returns an authorization code that you can use as the code parameter in a token request. https://${yourIDPDomain}/${OrganizationTenant}/connect/authorize?client_id=0oabucvyc38HLL1ef0h7&response_type=code&scope=openid&redirect_uri=http%3A%2F%2Flocalhost%3A8080&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601&nonce=g5ly497e8ps This request initiates the implicit flow, which gets an ID token and access token from the Authorization Server without the code exchange step. We use the same request as the first example, but with response_type=id_token token: https://${yourIDPDomain}/${OrganizationTenant}/connect/authorize?client_id=0oabv6kx4qq6h1U5l0h7&response_type=id_token token&scope=openid&redirect_uri=https%3A%2F%2Fwww.example.com&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601&nonce=foo Response example (success) In the authorization code flow, the endpoint sends a redirect header redirecting the user's browser back to the application that made the request. Depending on the grant type, IDP returns a code: https://www.example.com#code=QnowT-aeawtOJKp-MtkH&state=e97f03dd-d006-4e2d-8aa6-c221702a29ec or IDP returns a token: https://www.example.com#access_token=eyJhbGciOiJSUzI1NiJ9.eyJ2ZXIiOjEsImlzcyI6Imh0dHA6Ly9yYWluLm9rdGExLmNvbToxODAyIiwiaWF0IjoxNDQ5NjI0MDI2LCJleHAiOjE0NDk2Mjc2MjYsImp0aSI6IlVmU0lURzZCVVNfdHA3N21BTjJxIiwic2NvcGVzIjpbIm9wZW5pZCIsImVtYWlsIl0sImNsaWVudF9pZCI6InVBYXVub2ZXa2FESnh1a0NGZUJ4IiwidXNlcl9pZCI6IjAwdWlkNEJ4WHc2STZUVjRtMGczIn0.HaBu5oQxdVCIvea88HPgr2O5evqZlCT4UXH4UKhJnZ5px-ArNRqwhxXWhHJisslswjPpMkx1IgrudQIjzGYbtLFjrrg2ueiU5-YfmKuJuD6O2yPWGTsV7X6i7ABT6P-t8PRz_RNbk-U1GXWIEkNnEWbPqYDAm_Ofh7iW0Y8WDA5ez1jbtMvd-oXMvJLctRiACrTMLJQ2e5HkbUFxgXQ_rFPNHJbNSUBDLqdi2rg_ND64DLRlXRY7hupNsvWGo0gF4WEUk8IZeaLjKw8UoIs-ETEwJlAMcvkhoVVOsN5dPAaEKvbyvPC1hUGXb4uuThlwdD3ECJrtwgKqLqcWonNtiw&token_type=Bearer&expires_in=3600&scope=openid&state=e97f03dd-d006-4e2d-8aa6-c221702a29ec Response example (error) The requested scope is invalid: Example Domain /token POST ${baseUrl}/connect/token This endpoint returns access tokens, ID tokens, and refresh tokens, depending on the request parameters. For password, client credentials, and refresh token flows, calling /token is the only step of the flow. For the authorization code flow, calling /token is the second step of the flow. Request parameters The following parameters can be posted as a part of the URL-encoded form values to the API. The /token endpoint requires client authentication. See the Client authentication methods section for more information on which method to choose and how to use the parameters in your request. Parameter Description code Required if grant_type is authorization_code. The value is what was returned from the authorization endpoint. The code has a lifetime of 300 seconds. code_verifier Required if grant_type is authorization_code and code_challenge was specified in the original /authorize request. This value is the code verifier for PKCE. IDP uses it to recompute the code_challenge and verify if it matches the original code_challenge in the authorization request. grant_type Can be one of the following: authorization_code, password, client_credentials, refresh_token, or urn:ietf:params:oauth:grant-type:saml2-bearer Early Access . Determines the mechanism IDP uses to authorize the creation of the tokens. password Required if the grant_type is password. redirect_uri Required if grant_type is authorization_code. Specifies the callback location where the authorization was sent. This value must match the redirect_uri used to generate the original authorization_code. refresh_token Required if grant_type is refresh_token. The value is a valid refresh token that was returned from this endpoint previously. scope Required if password is the grant_type. This is a list of scopes that the client wants to be included in the access token. For the refresh_token grant type, these scopes have to be a subset of the scopes used to generate the refresh token in the first place. Response properties Based on the scopes requested. Generally speaking, the scopes specified in a request are included in the access token in the response. Property Description access_token An access token. token_type The audience of the token. expires_in The expiration time of the access token in seconds. scope The scopes contained in the access token. refresh_token An opaque refresh token. This is returned if the offline_access scope is granted. id_token An ID token. This is returned if the openid scope is granted. List of errors Error Id Details invalid_client The specified client_id isn't found. invalid_grant The code, refresh_token, or username and password combination is invalid, or the redirect_uri doesn't match the one used in the authorization request. invalid_request The request structure is invalid. For example, the basic authentication header is malformed, both header and form parameters are used for authentication, no authentication information is provided, or the request contains duplicate parameters. invalid_scope The scopes list contains an invalid or unsupported value. unsupported_grant_type The grant_type isn't authorization_code, refresh_token, or password. Request example curl -v -X POST \-H "Content-type:application/x-www-form-urlencoded" \"https://${IDPDomain}/${OrganizationTenant}/connect/token" \-d "client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}" Response example (success) { "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJ2ZXIiOjEsImlzcyI6Imh0dHA6Ly9yYWluLm9rdGExLmNvbToxODAyIiwiaWF0IjoxNDQ5NjI0MDI2LCJleHAiOjE0NDk2Mjc2MjYsImp0aSI6IlVmU0lURzZCVVNfdHA3N21BTjJxIiwic2NvcGVzIjpbIm9wZW5pZCIsImVtYWlsIl0sImNsaWVudF9pZCI6InVBYXVub2ZXa2FESnh1a0NGZUJ4IiwidXNlcl9pZCI6IjAwdWlkNEJ4WHc2STZUVjRtMGczIn0.HaBu5oQxdVCIvea88HPgr2O5evqZlCT4UXH4UKhJnZ5px-ArNRqwhxXWhHJisslswjPpMkx1IgrudQIjzGYbtLFjrrg2ueiU5-YfmKuJuD6O2yPWGTsV7X6i7ABT6P-t8PRz_RNbk-U1GXWIEkNnEWbPqYDAm_Ofh7iW0Y8WDA5ez1jbtMvd-oXMvJLctRiACrTMLJQ2e5HkbUFxgXQ_rFPNHJbNSUBDLqdi2rg_ND64DLRlXRY7hupNsvWGo0gF4WEUk8IZeaLjKw8UoIs-ETEwJlAMcvkhoVVOsN5dPAaEKvbyvPC1hUGXb4uuThlwdD3ECJrtwgKqLqcWonNtiw", "token_type" : "Bearer", "expires_in" : 3600, "scope" : "openid email", "refresh_token" : "a9VpZDRCeFh3Nkk2VdY", "id_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMHVpZDRCeFh3Nkk2VFY0bTBnMyIsImVtYWlsIjoid2VibWFzdGVyQGNsb3VkaXR1ZGUubmV0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInZlciI6MSwiaXNzIjoiaHR0cDovL3JhaW4ub2t0YTEuY29tOjE4MDIiLCJsb2dpbiI6ImFkbWluaXN0cmF0b3IxQGNsb3VkaXR1ZGUubmV0IiwiYXVkIjoidUFhdW5vZldrYURKeHVrQ0ZlQngiLCJpYXQiOjE0NDk2MjQwMjYsImV4cCI6MTQ0OTYyNzYyNiwiYW1yIjpbInB3ZCJdLCJqdGkiOiI0ZUFXSk9DTUIzU1g4WGV3RGZWUiIsImF1dGhfdGltZSI6MTQ0OTYyNDAyNiwiYXRfaGFzaCI6ImNwcUtmZFFBNWVIODkxRmY1b0pyX1EifQ.Btw6bUbZhRa89DsBb8KmL9rfhku--_mbNC2pgC8yu8obJnwO12nFBepui9KzbpJhGM91PqJwi_AylE6rp-ehamfnUAO4JL14PkemF45Pn3u_6KKwxJnxcWxLvMuuisnvIs7NScKpOAab6ayZU0VL8W6XAijQmnYTtMWQfSuaaR8rYOaWHrffh3OypvDdrQuYacbkT0csxdrayXfBG3UF5-ZAlhfch1fhFT3yZFdWwzkSDc0BGygfiFyNhCezfyT454wbciSZgrA9ROeHkfPCaX7KCFO8GgQEkGRoQntFBNjluFhNLJIUkEFovEDlfuB4tv_M8BM75celdy3jkpOurg"} Response example (error) HTTP 401 UnauthorizedContent-Type: application/json;charset=UTF-8{ "error" : "invalid_client", "error_description" : "No client credentials found."} /introspect POST${baseUrl}/connect/introspect This endpoint takes an access, ID, or refresh token, and returns a boolean that indicates whether it is active or not. If the token is active, additional data about the token is also returned. If the token is invalid, expired, or revoked, it is considered inactive. Be sure that you are using the /introspect endpoint of the same authorization server that you used to create the token. Although ID tokens can be sent to this endpoint, they are usually validated on the service provider or app side of a flow. Request parameters The following parameters can be posted as a part of the URL-encoded form values to the API.For public clients (such as single-page and mobile apps) that don't have a client_secret, you must include the client_id as a query parameter when calling the /introspect endpoint. Make sure that you aren't passing the Authorization header in the request. Parameter Description token An access token, ID token, or refresh token. token_type_hint Indicates the type of token being passed. Valid values are access_token, id_token and refresh_token. Response properties Based on the type of token and whether it is active, the returned JSON contains a different set of information. Besides the claims in the token, the possible top-level members include: Property Description active Indicates whether the token is active or not. aud The audience of the token. client_id The ID of the client associated with the token. device_id The ID of the device associated with the token exp The expiration time of the token in seconds since January 1, 1970 UTC. iat The issuing time of the token in seconds since January 1, 1970 UTC. iss The issuer of the token. jti The identifier of the token. nbf Identifies the time (a timestamp in seconds since January 1, 1970 UTC) before which the token must not be accepted for processing. scope A space-delimited list of scopes. sub The subject of the token. token_type The type of token. The value is always Bearer. uid The user ID. This parameter is returned only if the token is an access token and the subject is an end user. username The username associated with the token. List of errors Error Id Details invalid_client The specified client_id isn't found. invalid_request The request structure is invalid. For example, the basic authentication header is malformed, both header and form parameters are used for authentication, no authentication information is provided, or the request contains duplicate parameters. Response example (success, access token) { "active" : true, "token_type" : "Bearer", "scope" : "openid profile", "client_id" : "a9VpZDRCeFh3Nkk2VdYa", "username" : "john.doe@example.com", "exp" : 1451606400, "iat" : 1451602800, "sub" : "john.doe@example.com", "aud" : "https://${yourIDPDomain}", "iss" : "https://${yourIDPDomain}/oauth2/orsmsg0aWLdnF3spV0g3", "jti" : "AT.7P4KlczBYVcWLkxduEuKeZfeiNYkZIC9uGJ28Cc-YaI", "uid" : "00uid4BxXw6I6TV4m0g3"} Response example (success, refresh token) { "active" : true, "token_type" : "Bearer", "scope" : "openid profile email", "client_id" : "a9VpZDRCeFh3Nkk2VdYa", "username" : "john.doe@example.com", "exp" : 1451606400, "sub" : "john.doe@example.com", "device_id" : "q4SZgrA9sOeHkfst5uaa"} Response example (success, inactive token) { "active" : false} Response example (error) HTTP 401 UnauthorizedContent-Type: application/json;charset=UTF-8{ "error" : "invalid_client", "error_description" : "No client credentials found."} /revocation POST${baseUrl}/connect/revocation The API takes an access or refresh token and revokes it. Revoked tokens are considered inactive at the introspection endpoint. A client may only revoke its own tokens. See Revoke tokens for more information. Request parameters The following parameters can be posted as a part of the URL-encoded form values to the API. The /revoke endpoint requires client authentication. See the Client authentication methods section for more information on which method to choose and how to use the parameters in your request. Parameter Description token An access or refresh token. token_type_hint A hint of the type of token. Valid values are access_token and refresh_token. Response properties A successful revocation is denoted by an HTTP 200 OK response. Note that revoking an invalid, expired, or revoked token is still considered a success so as to not leak information. List of errors Error Id Details invalid_client The specified client_id wasn't found. invalid_request The request structure is invalid. For example, the basic authentication header is malformed, both header and form parameters are used for authentication, no authentication information is provided, or the request contains duplicate parameters. Response example (success) HTTP 200 OK Response example (error) HTTP 401 UnauthorizedContent-Type: application/json;charset=UTF-8{ "error": "invalid_client", "error_description": "No client credentials found."} /endsession GET${baseUrl}/connect/endsession Use this operation to log a user out by removing their IDP browser session. This endpoint takes an ID token and logs the user out of IDP if the subject matches the current IDP session. A post_logout_redirect_uri may be specified to redirect the browser after the logout is performed. Otherwise, the browser is redirected to the IDP sign-in page. If no IDP session exists, this endpoint has no effect and the browser is redirected immediately to the IDP sign-in page or the post_logout_redirect_uri (if specified). When making requests to the /logout endpoint, the browser (user agent) should be redirected to the endpoint. You can't use AJAX with this endpoint. Request parameters The following parameters can be included in the query string of the request: Parameter Description Required id_token_hint A valid ID token with a subject that matches the current session. TRUE post_logout_redirect_uri Location to redirect to after the logout is performed. It must match the value preregistered in IDP during client registration. FALSE state An optional value that is returned as a query parameter during the redirect to the post_logout_redirect_uri. FALSE Request examples This request initiates a logout and redirects to the IDP login page. GET https://{baseUrl}/connect/endsession?id_token_hint=${id_token} This request initiates a logout and redirects to the post_logout_redirect_uri. GET https://{baseUrl}/connect/endsession? id_token_hint=${id_token}& post_logout_redirect_uri=${post_logout_redirect_uri}& state=${state} Response example (success) This redirects the browser to either the IDP sign-in page or the specified logout redirect URI. HTTP 302 FoundLocation: https://example.com/post_logout/redirect&state=${state} Error conditions If the IDP session has expired (or doesn't exist), a logout request simply redirects to the IDP sign-in page or the post_logout_redirect_uri (if specified). If the ID token passed via id_token_hint is invalid, the browser is redirected to an error page. If the ID token is valid, but expired, and the subject matches the current IDP session, a logout request logs the user out and redirects the browser to the post_logout_redirect_uri. /userinfo GET${baseUrl}/connect/userinfo Returns information about the currently signed-in user. You must include an access token (returned from the authorization endpoint) in the HTTP Authorization header. Request example curl -v -X POST \-H "Authorization: Bearer ${access_token}" \"https://{baseUrl}/connect/userinfo" Response properties Returns a JSON document with claims about the currently authenticated end user. Response example (success) { "sub": "00uid4BxXw6I6TV4m0g3", "name" :"John Doe", "nickname":"Jimmy", "given_name":"John", "middle_name":"James", "family_name":"Doe", "profile":"https://example.com/john.doe", "zoneinfo":"America/Los_Angeles", "locale":"en-US", "updated_at":1311280970, "email":"john.doe@example.com", "email_verified":true, "address" : { "street_address":"123 Hollywood Blvd.", "locality":"Los Angeles", "region":"CA", "postal_code":"90210", "country":"US" }, "phone_number":"+1 (425) 555-1212"} Many of these claims are also included in the ID token, but calling this endpoint always returns all of the user's claims. The ID token can be configured to include a subset of the user's claims. See Scope-dependent claims for more information. Response example (error) HTTP 401 UnauthorizedWWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid" Response example (error) HTTP 403 ForbiddenExpires: 0WWW-Authenticate: Bearer error="insufficient_scope", error_description="The access token must provide access to at least one of these scopes - profile, email, address or phone" /.well-known/openid-configuration GET https://${yourIDPDomain}/${OrganizationTenant}/.well-known/openid-configuration Returns OpenID Connect metadata about your authorization server. This information can be used by clients to programmatically configure their interactions with IDP. Custom scopes are returned only when they are configured to be publicly discoverable. Custom claims are never returned. This API doesn't require any authentication. Response properties Property Description Type authorization_endpoint URL of the authorization server's authorization endpoint. String claims_supported A list of the claims supported by this authorization server. Array code_challenge_methods_supported JSON array that contains a list of PKCE code challenge methods supported by this authorization server. Array end_session_endpoint URL of the authorization server's logout endpoint. String grant_types_supported JSON array that contains a list of the grant type values that this authorization server supports. Array introspection_endpoint URL of the authorization server's introspection endpoint. String introspection_endpoint_auth_methods_supported JSON array that contains a list of client authentication methods supported by this introspection endpoint. Array issuer The authorization server's issuer identifier. In the context of this document, this is your authorization server's base URL. String jwks_uri URL of the authorization server's JSON Web Key Set document. String response_modes_supported JSON array that contains a list of the response_mode values that this authorization server supports. Array response_types_supported JSON array that contains a list of the response_type values that this authorization server supports. Can be a combination of code, token, and id_token. Array revocation_endpoint URL of the authorization server's revocation endpoint. String scopes_supported JSON array that contains a list of the scope values that this authorization server supports. Array token_endpoint URL of the authorization server's token endpoint. String Response example (success) { "issuer": "https://${yourIDPDomain}/${OrganizationTenant}", "authorization_endpoint": "https://{baseUrl}/connect/authorize", "token_endpoint": "https://{baseUrl}/connect/token", "userinfo_endpoint": "https://{baseUrl}/connect/userinfo", "jwks_uri": "https://{baseUrl}/keys", "response_types_supported": [ "code", "code id_token", "code token", "code id_token token", "id_token", "id_token token" ], "response_modes_supported": [ "query", "fragment", "form_post", "IDP_post_message" ], "grant_types_supported": [ "authorization_code", "implicit", "refresh_token", "password" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile", "address", "phone", "offline_access", "groups" ], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "none" ], "claims_supported": [ "iss", "ver", "sub", "aud", "iat", "exp", "jti", "auth_time", "amr", "idp", "nonce", "name", "nickname", "preferred_username", "given_name", "middle_name", "family_name", "email", "email_verified", "profile", "zoneinfo", "locale", "address", "phone_number", "picture", "website", "gender", "birthdate", "updated_at", "at_hash", "c_hash" ], "introspection_endpoint": "https://{baseUrl}/connect/introspect", "introspection_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "none" ], "revocation_endpoint": "https://{baseUrl}/revoke", "revocation_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "none" ], "end_session_endpoint": "https://{baseUrl}/logout", "request_parameter_supported": true, "request_object_signing_alg_values_supported": [ "HS256", "HS384", "HS512" ]} Response example (error) HTTP 404 Not Found{ "errorCode": "E0000007", "errorSummary": "Not found: Resource not found: ${authServerId} (AuthorizationServer)", "errorLink": "E0000007", "errorId": "oaeQdc5IvrlSGGnewf-cqqDqA", "errorCauses": []} Scopes OpenID Connect uses scope values to specify which access privileges are being requested for access tokens. The scopes associated with access tokens determine which claims are available when they are used to access the OIDC /userinfo endpoint. The following scopes are supported: Property Description Required openid Identifies the request as an OpenID Connect request. Yes profile Requests access to the end user's default profile claims. No email Requests access to the email and email_verified claims. No phone Requests access to the phone_number and phone_number_verified claims. No address Requests access to the address claim. No groups Requests access to the groups claim. No offline_access Requests a refresh token used to obtain more access tokens without re-prompting the user for authentication. No Scope values openid is required for any OpenID request connect flow. If the openid scope value isn't present, the request may be a valid OAuth 2.0 request, but it's not an OpenID Connect request. profile requests access to these default profile claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo,locale, and updated_at. offline_access can only be requested in combination with a response_type that contains code. If the response_type doesn't contain code, offline_access is ignored. For more information about offline_access, see the OIDC spec. Tokens and claims This section contains some general information about claims, as well as detailed information about access and ID tokens. Access Token ID Token Refresh Token Token lifetime When you are using the IDP Authorization Server, the lifetime of the JWT tokens is hard-coded to the following values: ID token: 60 minutes Access token: 60 minutes Refresh token: 90 days Claims Tokens issued by IDP contain claims that are statements about a subject (user). For example, the claim can be about a name, identity, key, group, or privilege. The claims in a security token are dependent upon the type of token, the type of credential used to authenticate the user, and the application configuration. The claims requested by the profile, email, address, and phone scope values are returned from the /userinfo endpoint when a response_type value is used that results in an access token being issued. However, when no access token is issued (which is the case for the response_type value id_token), the resulting claims are returned in the ID token. Access token Use of the access token differs depending on whether you are using the IDP Org Authorization Server or a Custom Authorization Server. While the structure of an access token retrieved from a Custom Authorization Server is guaranteed to not change, the structure of the access token issued by the IDP Org Authorization Server is subject to change. An access token is a JSON web token (JWT) encoded in Base64 URL-encoded format that contains a header, payload, and signature. A resource server can authorize the client to access particular resources based on the scopes and claims in the access token. The lifetime of an access token can be configured in access policies. If the client that issued the token is deactivated, the token is immediately and permanently invalidated. Reactivating the client doesn't make the token valid again. Access token header { "alg": "RS256", "kid": "45js03w0djwedsw"} Access token payload { "ver": 1, "jti": "AT.0mP4JKAZX1iACIT4vbEDF7LpvDVjxypPMf0D7uX39RE", "iss": "https://${yourIDPDomain}/oauth2/0oacqf8qaJw56czJi0g4", "aud": "https://api.example.com", "sub": "00ujmkLgagxeRrAg20g3", "iat": 1467145094, "exp": 1467148694, "cid": "nmdP1fcyvdVO11AL7ECm", "uid": "00ujmkLgagxeRrAg20g3", "scp": [ "openid", "email", "flights", "custom" ], "custom_claim": "CustomValue"} Access token signature This is a digital signature that IDP generates using the public key identified by the kid property in the header section. Access token scopes and claims Access tokens include reserved scopes and claims and can optionally include custom scopes and claims. Scopes are requested in the initial authorization request, and the Authorization Server uses the access policies to decide whether they can be granted. If any of the requested scopes are rejected by the Access Policies, the request is rejected. Based on the granted scopes, claims are added into the access token returned from the request. Reserved scopes and claims IDP defines a number of reserved scopes and claims that can't be overridden. Reserved scopes Reserved claims in the header section Reserved claims in the payload section Reserved scopes openid, profile, email, address, phone, offline_access, and groups are available to ID tokens and access tokens, using either the IDP Org Authorization Server or a Custom Authorization Server. For details, see Scopes. All of these scopes except groups are defined in the OpenID Connect specification. Reserved claims in the header section The header only includes the following reserved claims: Property Description alg Identifies the digital signature algorithm used. This is always RS256. kid Identifies the public-key used to sign the access_token. The corresponding public-key can be found via the JWKS in the discovery document. Reserved claims in the payload section The payload includes the following reserved claims: Property Description aud Identifies the audience (resource URI or server) that this access token is intended for. cid Client ID of the client that requested the access token. exp The time the access token expires, represented in Unix time (seconds). iat The time the access token was issued, represented in Unix time (seconds). iss The Issuer Identifier of the response. This value is the unique identifier for the Authorization Server instance. jti A unique identifier for this access token for debugging and revocation purposes. scp Array of scopes that are granted to this access token. sub The subject. A name for the user or a unique identifier for the client. uid A unique identifier for the user. It isn't included in the access token if there is no user bound to it. ver The semantic version of the access token. Custom scopes If the request that generates the access token contains any custom scopes, those scopes are a part of the scp claim together with the reserved scopes provided from the OIDC specification. The names of your custom scopes must conform to the OAuth 2.0 specification. Scope names can contain the characters < (less than) or > (greater than), but not both characters. Custom claims Custom claims are associated with scopes. In general, granting a custom scope means a custom claim is added to the token. However, the specifics depend on which claims are requested, whether the request is to the IDP Org Authorization Server or a Custom Authorization Server, and some configuration choices. Quick Reference: Which token has which claims? Custom claims are configured in the Custom Authorization Server, and returned depending on whether it matches a scope in the request, and also depending on the token type, authorization server type, and the token and claim configuration set in the authorization server: Base claims are always returned in ID tokens and access tokens for both authorization server types (IDP Org Authorization Server or Custom Authorization Server). Scope-dependent claims are returned in tokens depending on the response type for either authorization server type. See the second table in the Scope-dependent claims topic for details. Custom claims require configuration in the Custom Authorization Server. You can specify that claims be returned in each token (ID or access) always or only when requested. Assuming a claim matches a requested scope, it is returned to the ID token if there is no access token requested. The ID token or access token may not include all claims associated with the requested scopes. The UserInfo endpoint always contains a full set of claims for the requested scopes. ID token OpenID Connect introduces an ID token that is a JSON Web Token (JWT) that contains information about an authentication event and claims about the authenticated user. Clients can use any of the following sequences of operations to obtain an ID token: Authorization code flow or Authorization code with PKCE flow -- the client obtains an authorization code from the authorization server's /authorize endpoint and uses it to obtain an ID token and an access token from the authorization server's /token endpoint. Implicit flow -- the client obtains an ID token and optionally an access token directly from the authorization server's /authorize endpoint. Clients should always validate ID tokens to ensure their integrity. The ID tokens returned by the /authorize endpoint (implicit flow) or the /token endpoint (authorization code flow) are identical, except if: You are using the implicit flow. If so, the nonce parameter is required in the initial /authorize request, and the ID token includes a nonce claim that should be validated to make sure it matches the nonce value passed to /authorize. Both an ID and an access token were requested. If so, the ID token includes the at_hash parameter that can be validated against the hash of the access token to guarantee that the access token is genuine. The ID token consists of three period-separated, Base64 URL-encoded JSON segments: a header, the payload, and the signature. ID token header { "alg": "RS256", "kid": "45js03w0djwedsw"} ID token payload { "ver": 1, "sub": "00uid4BxXw6I6TV4m0g3", "iss": "https://{yourIDPDomain.com}", "aud": "uAaunofWkaDJxukCFeBx", "iat": 1449624026, "exp": 1449627626, "amr": [ "pwd" ], "jti": "ID.4eAWJOCMB3SX8XewDfVR", "auth_time": 1449624026, "at_hash": "cpqKfdQA5eH891Ff5oJr_Q", "name" :"John Doe", "nickname":"Jimmy", "preferred_username": "john.doe@example.com", "given_name":"John", "middle_name":"James", "family_name":"Doe", "profile":"https://example.com/john.doe", "zoneinfo":"America/Los_Angeles", "locale":"en-US", "updated_at":1311280970, "email":"john.doe@example.com", "email_verified":true, "address" : { "street_address": "123 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US" }, "phone_number":"+1 (425) 555-1212"} ID token signature This is the digital signature that IDP signs using the public key identified by the kid property in the Header section. ID token claims The Header and Payload sections contain claims. Claims in the Header section Claims in the Header are always returned. Property Description alg Identifies the digital signature algorithm used. This is always RS256. kid Identifies the public key used to verify the ID token. The corresponding public key can be found via the JWKS in the discovery document. Claims in the Payload section Claims in the payload are either base claims, independent of scope (always returned), or dependent on scope (not always returned). Base claims (always present) Property Description DataType Example amr JSON array of strings that are identifiers for authentication methods (opens new window)used in the authentication. Array [ "pwd", "mfa", "otp", "kba", "sms", "swk", "hwk" ] aud Identifies the audience that this ID token is intended for. It is one of your application's OAuth 2.0 client IDs. String 6joRGIzNCaJfdCPzRjlh auth_time The time the end user was authenticated, represented in Unix time (seconds). Integer 1311280970 exp The time the ID token expires, represented in Unix time (seconds). Integer 1311280970 iat The time the ID token was issued, represented in Unix time (seconds). Integer 1311280970 idp The IDP org ID or the ID of an Identity Provider if this authentication used Social Authentication or Inbound SAML. String 00ok1u7AsAkrwdZL3z0g3 iss The URL of the authorization server that issued this ID token. String https://$ jti A unique identifier for this ID token for debugging and revocation purposes. String Tlenfse93dgkaksginv sub The subject. A unique identifier for the user. String 00uk1u7AsAk6dZL3z0g3 ver The semantic version of the ID token. Integer 1 Scope-dependent claims (not always returned) Property Required Scope Description DataType Example name profile User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the user's locale and preferences. String John Doe preferred_username profile The IDP login (username) for the end user. String john.doe@example.com nickname profile Casual name of the user that may or may not be the same as the given_name. String Jimmy preferred_username profile The chosen login (username) for the end user. By default this is the IDP username. String john.doe@example.com given_name profile Given name(s) or first name(s) of the user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. String John middle_name profile Middle name(s) of the user. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names aren't used. String James family_name profile Surname(s) or last name(s) of the user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. String Doe profile profile URL of the user's profile page. String https://profile.wordpress.com/john.doe zoneinfo profile String that represents the user's time zone. String America/Los_Angeles locale profile Language and ISO3166‑1 country code in uppercase, separated by a dash. String en-US updated_at profile Time the user's information was last updated, represented in Unix time (seconds). Integer 1311280970 email email User's preferred email address. The resource provider must not rely on this value being unique. String john.doe@example.com email_verified email True if the user's email address (IDP primary email) has been verified; otherwise false. boolean true address address User's preferred postal address. The value of the address member is a JSON structure that contains street_address, locality, region, postal_code, and country. JSON structure { "street_address": "123 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US" } phone_number phone User's preferred telephone number in E.164 format. String +1 (425) 555-1212 groups groups The groups that the user is a member of that also match the ID token group filter of the client app. List ["MyGroup1", "MyGroup2", "MyGroup3"] Be aware of the following before you work with scope-dependent claims: To protect against arbitrarily large numbers of groups matching the group filter, the groups claim has a limit of 100. If more than 100 groups match the filter, then the request fails. Expect that this limit may change in the future. For more information about configuring an app for OpenID Connect, including group claims, see Create a client application. Scope-dependent claims are returned differently depending on the values in response_type and the scopes requested: Response Type Claims Returned in ID Token from Org AS Claims Returned in ID Token from Custom AS Claims Returned from Userinfo Endpoint code N/A N/A N/A token N/A N/A N/A id_token Claims associated with requested scopes. Claims associated with requested scopes. N/A id_token code Claims associated with requested scopes. Claims associated with requested scopes. N/A id_token token email if email scope is requested; name and preferred_username if profile scope is requested Claims associated with the requested scopes and the alwaysIncludeinToken property set to true. Claims associated with the requested scopes code id_token token email if email scope is requested; name and preferred_username if profile scope is requested Claims associated with the requested scopes and the alwaysIncludeinToken property set to true. Claims associated with the requested scopes The full set of claims for the requested scopes is available via the /${OrganizationTenant}/userinfo endpoint. Call this endpoint using the access token. Refresh token Refresh tokens are opaque. Client authentication methods Some endpoints require client authentication. To make requests to these endpoints, you must include a header or parameter in the request depending on the authentication method that the application is configured with. When registering an OAuth 2.0 client application, specify an authentication method by including the token_endpoint_auth_method parameter. If you don't specify a method when registering your client, the default method is client_secret_basic. IDP supports the following authentication methods, detailed in the sections below: client_secret_basic, client_secret_post, client_secret_jwt: Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use none below. private_key_jwt: Use this when you want maximum security. This method is more complex and requires a server, so it can't be used with public clients. none - Use this with clients that don't have a client secret (such as applications that use the authorization code flow with PKCE or the implicit flow). Client secret If your client's token_endpoint_auth_method is either client_secret_basic or client_secret_post, include the client secret in outgoing requests. client_secret_basic: Provide the client_id and client_secret values in the Authorization header as a Basic auth base64-encoded string with the POST request:Authorization: Basic ${Base64(<client_id>:<client_secret>)} client_secret_post: Provide the client_id and client_secret as additional parameters in the POST request body. JWT with shared key If you configured your client to use the client_secret_jwt client authentication method: Provide the client_id in a JWT that you sign with the client_secret using an HMAC SHA algorithm (HS256, HS384, or HS512). The JWT must also contain other values, such as issuer and subject. See Token claims for client authentication with client secret or private key JWT. JWTs with a shared key require a secret that is at least 32 characters in length to satisfy HS256 cryptographic minimums. Clients that attempt to set token_endpoint_auth_method to client_secret_jwt with an imported secret less than 32 characters will receive a validation error. Clients that send IDP a JWT for verification signed with HS256, HS384, or HS512 with a secret less than 32 characters will receive an error: The client secret is too short to verify a JWT HMAC.. After you create the JWT, in the request you need to specify the client_assertion_type as urn:ietf:params:oauth:client-assertion-type:jwt-bearer and specify the JWT as the value for the client_assertion parameter. For example: POST /token HTTP/1.1Host: server.example.comContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code& code=i1WsRn1uB1& client_id=0oajncakofQmjxlSw0h3 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT JWT with private key This method is similar to JWT with shared key, but uses a public/private key pair for more security. The main benefit of this method is you can generate the private key on your own servers and never have it leave there for any reason, since you only need to provide the public key to IDP. This is better than client_secret_jwt since IDP must know what the client_secret string is beforehand, so there are more places that it could in theory be compromised. If you configured your client to use the private_key_jwt client authentication method: Provide the client_id in a JWT that you sign with your private key using an RSA or ECDSA algorithm (RS256, RS384, RS512, ES256, ES384, ES512). See Build a JWT for client authentication. The JWT must also contain other values, such as issuer and subject. See Token claims for client authentication with client secret or private key JWT. The private key that you use to sign the JWT must have the corresponding public key registered in the client's JWKSet. After you create the JWT, in the request you need to specify the client_assertion_type as urn:ietf:params:oauth:client-assertion-type:jwt-bearer and specify the JWT as the value for the client_assertion parameter. For example: POST /token HTTP/1.1Host: server.example.comContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code& code=i1WsRn1uB1& client_id=0oajncakofQmjxlSw0h3 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT None Specify none when the client is a public client and doesn't have a client secret. Only the client_id is sent in the request body. Token claims for client authentication with client secret or private key JWT If you use a JWT for client authentication (client_secret_jwt or private_key_jwt), use the following token claims: Token Claims Description Type aud Required. The full URL of the resource you're using the JWT to authenticate to. String exp Required. The expiration time of the token in seconds since January 1, 1970 UTC. Integer jti Optional. The identifier of the token. String iat Optional. The issuing time of the token in seconds since January 1, 1970 UTC. Integer iss Required. The issuer of the token. This value must be the same as the client_id. String sub Required. The subject of the token. This value must be the same as the client_id. String Parameter details If jti is specified, the token can only be used once. So, for example, subsequent token requests won't succeed. The exp claim fails the request if the expiration time is more than one hour in the future or has already expired. If iat is specified, then it must be a time before the request is received.