1. Dualog Support
  2. SHORE ADMINISTRATION
  3. Dualog Access

Dualog Access - API Documentation (Endpoint)

Avatar
Lewis Campbell
Follow

LIST OF ENDPOINT

This article covers the following list of endpoint:

  1. Discovery
  2. Authorize
  3. Token
  4. User Info
  5. Device Authorisation
  6. Introspection (Coming Soon)
  7. Revocation
  8. End Session
  • DISCOVERY ENDPOINT

The discovery endpoint is used to retrieve metadata about the Dualog Access Server:

  • Issuer Name
  • Key Material
  • Supported Scopes
  • etc.

The discovery end-point URL will consist of the IP/port where the end-point is located.

Examples: 

https://127.0.0.1/something/something_else
https://192.168.1.1/something/something_else
  • AUTHORIZE ENDPOINT

Use the authorized endpoint to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.

Parameters:

  • client_id - client identifier (Required)
  • request - Instead of providing all parameters as individual query string parameters, they can be provided a subset or all of them as a JWT.
  • request_uri - URL of a pre-packaged JWT containing request parameters.
  • 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 - The identity server will echo back the state value on the token response, this is for the round-tripping state between client and provider, correlating request and response, and CSRF/replay protection. (Recommended)
  • nonce - Dualog Access will echo back the nonce value in the identity token, this is for replay protection. (Required for identity tokens via an 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 challenge is hashed with SHA256.
  • login_hint - This 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 login session exceeds the max-age (In seconds), the login UI will be shown.
  • acr_values - Allows passing of optional authentication-related information
  • 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 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

TOKEN ENDPOINT

The token endpoint can be used to programmatically request tokens.

Supported grants:

  • Password
  • authorization_code
  • client_credentials
  • refresh_token
  • urn:ietf:params:oauth:grant-type:device_code

Furthermore, the token endpoint can be extended to support extension grant types.

Parameters:

  • 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, urn:ietf:params:oauth:grant-type:device_code 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 – Dualog Access 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)
  • device_code - The device code (Required for urn:ietf:params:oauth:grant-type:device_code grant type)

Example:

POST /connect/token
CONTENT-TYPE application/x-www-form-urlencoded
client_id=client1&
client_secret=secret&
grant_type=authorization_code&
code=hdh922&
redirect_uri=https://myapp.com/callback

USER INFO ENDPOINT

The UserInfo endpoint can be used to retrieve identity information about a user.

The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims. (At least the openid scope is required).

Example:

GET /connect/userinfo
Authorization: Bearer 
<access_token>
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "248289761001",
"name": "Bob Smith",
"given_name": "Bob",
"family_name": "Smith",
"role": [
"user",
"admin"
]
}

DEVICE AUTHORIZATION ENDPOINT

The device authorization endpoint can be used to request device and user codes. This endpoint is used to start the device flow authorization process.

The URL for the end session endpoint is available via the discovery endpoint.

Parameters:

  • client_id - client identifier (Required)
  • client_secret - client secret either in the post body or as a basic authentication header. (Optional)
  • scope - One or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.

Example:

POST /connect/deviceauthorization
client_id=client1&
client_secret=secret&
scope=openid api1

INTROSPECTION ENDPOINT (COMING SOON)

The introspection endpoint can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries).

The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the ApiResource.

Example:

POST /connect/introspect
Authorization: Basic xxxyyy
token=<token>

A successful response will return a status code of 200 and either an active or inactive token:

{
"active": true,
"sub": "123"
}

Unknown or expired tokens will be marked as inactive:

{
"active": false,
}

An invalid request will return a 400, an unauthorized request 401.

REVOCATION ENDPOINT

This endpoint allows revoking access tokens (reference tokens only) and refreshes tokens. It implements the token revocation specification (RFC 7009).

Parameters:

  • token - The token to revoke (Required)
  • token_type_hint - Either access_token or refresh_token (Optional)

Example:

POST /connect/revocation HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

END SESSION ENDPOINT

The end session endpoint can be used to trigger single sign-out.

To use the end session endpoint a client application will redirect the user’s browser to the end session URL. All applications the user has logged into via the browser during the user’s session can participate in the sign-out.

The URL for the end session endpoint is available via the discovery endpoint.

Parameters:

  • id_token_hint

When the user is redirected to the endpoint, they will be prompted if they really want to sign out. This prompt can be bypassed by a client sending the original id_token received from authentication. This is passed as a query string parameter called id_token_hint.

  • post_logout_redirect_uri

If a valid id_token_hint is passed, then the client may also send a post_logout_redirect_uri parameter. This can be used to allow the user to redirect back to the client after sign-out. The value must match one of the client’s pre-configured PostLogoutRedirectUris.

  • State

If a valid post_logout_redirect_uri is passed, then the client may also send a state parameter. This will be returned to the client as a query string parameter after the user redirects to the client. This is typically used by clients to round-trip state across the redirect.

Example:

GET /connect/endsession?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlOGFkZmMzMjU1OTEyNzI0ZDY4NWZmYmIwOThjNDEyIiwidHlwIjoiSldUIn0.eyJuYmYiOjE0OTE3NjUzMjEsImV4cCI6MTQ5MTc2NTYyMSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo1MDAwIiwiYXVkIjoianNfb2lkYyIsIm5vbmNlIjoiYTQwNGFjN2NjYWEwNGFmNzkzNmJjYTkyNTJkYTRhODUiLCJpYXQiOjE0OTE3NjUzMjEsInNpZCI6IjI2YTYzNWVmOTQ2ZjRiZGU3ZWUzMzQ2ZjFmMWY1NTZjIiwic3ViIjoiODg0MjExMTMiLCJhdXRoX3RpbWUiOjE0OTE3NjUzMTksImlkcCI6ImxvY2FsIiwiYW1yIjpbInB3ZCJdfQ.STzOWoeVYMtZdRAeRT95cMYEmClixWkmGwVH2Yyiks9BETotbSZiSfgE5kRh72kghN78N3-RgCTUmM2edB3bZx4H5ut3wWsBnZtQ2JLfhTwJAjaLE9Ykt68ovNJySbm8hjZhHzPWKh55jzshivQvTX0GdtlbcDoEA1oNONxHkpDIcr3pRoGi6YveEAFsGOeSQwzT76aId-rAALhFPkyKnVc-uB8IHtGNSyRWLFhwVqAdS3fRNO7iIs5hYRxeFSU7a5ZuUqZ6RRi-bcDhI-djKO5uAwiyhfpbpYcaY_TxXWoCmq8N8uAw9zqFsQUwcXymfOAi2UF3eFZt02hBu-shKA&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A7017%2Findex.html

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.

Articles in this section