OpenID Connect
The OpenID Connect identity provider has multiple endpoints with which the user and client application interact.
OpenID Connect describes a metadata document that contains most of the information required for an app to perform sign-in. This includes all endpoint URLs in use and the location of the service’s public signing keys.
The metadata is a simple JavaScript Object Notation (JSON) document and can be found at:
https://{environment}.superoffice.com/login/.well-known/openid-configuration
The environment subdomain is unique for each application environment:
Environment-specific sub-domains
Only use these root sub-domains.
Caution
DO NOT USE numbered sub-domains for authentication/authorization! Numbered sub-domains are only for API data access, not obtaining authorization tokens.
| Environment | Sub-domain |
|---|---|
| Development | sod |
| Stage | qaonline |
| Production | online |
Example excerpt
{
"issuer": "https://sod.superoffice.com",
"authorization_endpoint": "https://sod.superoffice.com/login/common/oauth/authorize",
"token_endpoint": "https://sod.superoffice.com/login/common/oauth/tokens",
"jwks_uri": "https://sod.superoffice.com/login/.well-known/jwks",
"scopes_supported": [
"openid"
],
"response_modes_supported": [
"form_post",
"fragment",
"query"
],
"response_types_supported": [
"code",
"id_token",
"code id_token",
"token id_token",
"token"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic"
],
"grant_types_supported": [
"implicit",
"authorization_code",
"refresh_token"
],
}
Endpoints
Authorize endpoint
This is where the user is asked to authenticate and grant the partner application consent to access their identity. When consent is given, this endpoint passes back an Authorization Code.
Here, the user interacts indirectly with the identity provider through a user agent, such as a browser.
Tokens endpoint
This endpoint authenticates the client application. It also exchanges the Authorization Code from the authorization endpoint for an ID token, an access token, and a refresh token.
Access tokens
Access tokens are used in token-based authentication to allow an application to access an API.
The SuperOffice access token is proprietary and not a standard JWT. It cannot be inspected with tools such as jwt.io.
The access token is primarily a means to call a target API. It is:
- used as a credential when calling the API
- time-limited and needs to be refreshed periodically (3600 seconds / 1 hour)
You will receive the access token in the authorization response. It is up to the application to securely store the access token.
You need to get a new access token when:
- the application user signs in for the 1st time
- the previous token expires
Refresh tokens
Refresh tokens are used in token-based authentication to get a new access token and ID token when those expire.
The refresh token is sent in a request:
- when the access (or ID) token has expired
- when you want to update the claims in an ID token
The refresh token is only returned in the authentication code flow. To read more about how to use a refresh token, visit the Authorization Code flow section.
JWKS endpoint
The JSON Web Key Set (JWKS) is a set of keys that contains the public certificate used to verify any JSON web token (JWT) issued by SuperID.
UserInfo endpoint
Not supported, however some OpenID Connect clients allow post-authentication hooks to populate a users profile.
In that case, assuming the hook provides the access_token, one can use the v1/User/currentPrincipal REST endpoint to obtain current users profile details.
Examples:
End Session endpoint
The end session endpoint can be used to trigger single sign-out (see spec).
Revocation endpoint
This endpoint is used to revoke access tokens (reference tokens only) and refresh token.