Endpoints

OAuth endpoints are the URLs used to make OAuth authentication requests. There are several endpoints:

 

Discovery Endpoint
The discovery endpoint can be used to retrieve metadata about your OneContactLogin. It returns information like the issuer name, key material, supported scopes etc.

The discovery endpoint is available via /.well-known/openid-configuration relative to the base address, e.g.:

https://demo.identityserver.io/.well-known/openid-configuration

 

Token Endpoint
The token endpoint can be used to programmatically request tokens. It supports the password, authorization_code, client_credentials and refresh_token grant types. Furthermore the token endpoint can be extended to support extension grant types.

client_id: Client identifier (required).

client_secret: Client secret either in the post body, or as a basic authentication header. Optional.

grant_type: Authorization_code, client_credentials, password, refresh_token or custom.

scope: One or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.

redirect_uri: Required for the authorization_code grant type.

code: The authorization code (required for authorization_code grant type).

code_verifier: PKCE proof key.

username: Resource owner username (required for password grant type).

password: Resource owner password (required for password grant type).

acr_values: Allows passing in additional authentication related information for the password grant type - identityserver special cases the following proprietary acr_values:

  • idp:name_of_idp: Bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration).
  • tenant:name_of_tenant: Can be used to pass a tenant name to the token endpoint.

refresh_token: The refresh token (required for refresh_token grant type).

Example:

POST /connect/token
client_id=client1&
client_secret=secret&
grant_type=authorization_code&
code=hdh922&
redirect_uri=https://myapp.com/callback

 

Authorize Endpoint
The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.

client_id: Identifier of the client (required).

scope: One or more registered scopes (required).

redirect_uri: Must exactly match one of the allowed redirect URIs for that client (required).

response_type

  • id_token: Requests an identity token (only identity scopes are allowed).
  • token: Requests an access token (only resource scopes are allowed).
  • id_token token: Requests an identity token and an access token.
  • code: Requests an authorization code.
  • code id_token: Requests an authorization code and identity token.
  • code id_token token: Requests an authorization code, identity token and access token.

response_mode

  • form_post: Sends the token response as a form post instead of a fragment encoded redirect (optional).

state: OneContactLogin will echo back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection. (recommended)

nonce: OneContactLogin will echo back the nonce value in the identity token, this is for replay protection).

Required for identity tokens via implicit grant.

prompt

  • none: No UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returned.
  • login: The login UI will be shown, even if the user is already signed-in and has a valid session.

code_challenge: Sends the code challenge for PKCE.

code_challenge_method

  • plain: Indicates that the challenge is using plain text (not recommended) S256 indicates the the challenge is hashed with SHA256.

login_hint: Can be used to pre-fill the username field on the login page.

ui_locales: Gives a hint about the desired display language of the login UI.

max_age: If the user’s logon session exceeds the max age (in seconds), the login UI will be shown.

acr_values: Allows passing in additional authentication related information - identityserver special cases the following proprietary acr_values:

  • idp:name_of_idp: Bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration).
  • name_of_tenant: Can be used to pass a tenant name to the login UI.

Example:

GET /connect/authorize?
client_id=client1&
scope=openid email api1&
response_type=id_token token&
redirect_uri=https://myapp/callback&
state=abc&
nonce=xyz