OpenID Connect (OAuth 2) Overview

Overview

This page provides a broad overview of how OpenID Connect and OAuth 2 are implemented.

Terminology

IdP / OP: Identity Provider / OpenID Provider. Refers to this Cloud SSO product and, indirectly, iMIS – which is always the IdP.
RP: Relying Party. Refers to the third party that has an app registration and is using the SSO.
Redirect URI(s): One or more fully-qualified URLs that must be whitelisted in the client application settings, in order for the OpenID server to know which URL(s) are safe to redirect to. Multiple values, including dev/test/non-public servers, and localhost, are supported. This value is always provided by the third party system / library.
code / auth code: A short alphanumeric code passed from the IdP to the RP, good for 60 seconds, that can be exchanged for an access token.
access token: An alphanumeric token that can be used to determine if a user is signed in, and retrieve their profile information.
id token: A JWT token (encoded JSON object) that represents information about the current sign in, including the username of the user, the website that made the request, the website that issued the token, when the token expires, and more.
refresh token: An alphanumeric token that can be passed to the /openid/token endpoint in order to renew an access token that is about to expire. A new access token is returned, and the expiration is extended. A token can be refreshed at any time. If a token is refreshed, the old access token will no longer work.

Discovery Document

Certain OpenID Connect clients, including CSI's Cloud SSO app, support a discovery document. This JSON document contains all supported URLs and operations by this Cloud SSO app / OpenID Connect implementation.

The discovery document URL is always: https://{sso.example.org}/.well-known/openid-configuration

Endpoint List

The following endpoints are available with the Cloud SSO app. These endpoints satisfy various OpenID and OAuth 2.0 protocol requirements.

All endpoints are prefixed with your base URL, that is typically https://sso.example.org/ or https://auth.exmaple.org/.

Endpoint	Relative Path	Description	Reference Document
Authorization	/openid/authenticate	Used as the SSO initiation / starting endpoint. Redirecting to this endpoint with the proper parameters will cause an Open ID authentication/authorization flow, and will eventually redirect back to the supplied `redirect_uri`.	RFC 6749 (OAuth 2.0)
Token	/openid/token	Used to exchange a temporary auth code or a refresh token for an access token.	RFC 6749 (OAuth 2.0)
User Info	/openid/userinfo	Used to retrieve information about the current user, given an access token.	OpenID.Core
Introspection	/openid/token/introspection	Used to provide information about the token, including if it is active or not, given an access token or a refresh token.	RFC 7662 (OAuth 2.0)
Revocation	/openid/token/revoke	Used to revoke an active access token or refresh token, causing it to become inactive.	RFC 7009 (OAuth 2.0)
Sign Out	/openid/signout	Used to sign the user out, and revoke the access token.	OpenID.SessionManagement

Primary Endpoint Details

Parameter types:

QS: A query string value in the request URL
Header: A value passed in via the specified HTTP header
Form: A value passed as the body of the POST request, with a Content-Type of application/x-www-form-urlencoded.

HTTP	Endpoint	Parameters	Returns
GET (Browser Redirect)	/openid/authenticate	[QS] `scope`: Must be set to "openid profile" for the Cloud SSO. No other scopes are supported. [QS] `response_type`: Must be "code". If implicit flow is enabled, this value can also be "id_token". [QS] `client_id`: Pass in the client ID value (a GUID) from the App Registration. [QS] `redirect_uri`: Pass in the desired destination URL where the OAuth flow should continue. Endpoint must be registered in the App Registration. This value is case sensitive. [QS] `state`: Optional. Pass in a string containing some state (typically a Base64-encoded payload) which will be returned back to the redirect_uri endpoint. [QS] nonce: Optional. String value to use as-is within the JWT token as a "nonce" value. It is the client's responsibility to generate a sufficiently random nonce and check for replays. [QS] `prompt`: Optional. One of "none", "login", or "consent". "login" will ignore the user's session and force a login, "consent" will always display the OAuth 2 consent screen. [QS] `login_hint`: Optional. A username to pre-populate into the Username field for who this user might be. The user may change this value.	302 Redirect: GET [Redirect URI] ?code=<Temp Auth Code> &state=<Your State Value> GET [Redirect URI] ?error=<Error Code> &state=<Your State Value> 400 Bad Request: application/json error: Contains the error code.
POST (Server-to-Server)	/openid/token	[Header] `Authorization`: Basic authentication. Username: Client ID, Password: Client Secret (Auth Method: Client Secret Basic) – OR – [Form] `client_id`: Pass in the client ID value (a GUID) from the App Registration. (Auth Method: Client Secret Post) [Form] `client_secret`: Pass in the client secret value (a random alphanumeric string) from the App Registration. (Auth Method: Client Secret Post) – AND – [Form] `grant_type`: Must be "authorization_code". [Form] code: Pass the "Temp Auth Code" from the response via the Authentication flow above. [Form] redirect_uri: Must be the same redirect URI that was used in the previous Authentication flow above.	200 OK: application/json access_token: A random string that can be used for subsequent requests, e.g. to the /userinfo endpoint. token_type: "Bearer" refresh_token: A shorter random string that can be used to refresh this token via this endpoint. expires_in: The number of seconds since this request was received that the token expires in. id_token: A JWT token containing the OpenID ID token. Contains the username of the user (the sub claim) and other standard JWT properties such as aud, iat, nbf, jti, and iss. 400 Bad Request: application/json error: Contains the error code.
GET (Server-to-Server)	/openid/userinfo	[Header] `Authorization`: Bearer authentication. Pass in the access token that was provided via the /openid/token endpoint. Note that the access token and ID token / JWT token are different. The access token is a random alphanumeric string with a length between 40 and 50 characters.	200 OK: application/json JSON properties are represented by the user's profile data that was returned from the IQA.
POST (Server-to-Server)	/openid/token	[Form] `grant_type`: Must be "refresh_token". [Form] `client_id`: Pass in the client ID value (a GUID) from the App Registration. [Form] `client_secret`: Pass in the client secret value (a random alphanumeric string) from the App Registration. [Form] `refresh_token`: Pass in the refresh token value obtained from the authorization code response above. [Form] `scope`: Must be set to "openid profile" for the Cloud SSO. No other scopes are supported.	200 OK: application/json access_token: A random string that can be used for subsequent requests, e.g. to the /userinfo endpoint. token_type: "Bearer" refresh_token: A shorter random string that can be used to refresh this token via this endpoint. expires_in: The number of seconds since this request was received that the token expires in. id_token: A JWT token containing the OpenID ID token. Contains the username of the user (the sub claim) and other standard JWT properties such as aud, iat, nbf, jti, and iss. 400 Bad Request: application/json error: Contains the error code.
GET (Browser Redirect)	/openid/signout	[QS] `id_token_hint`: Required. The JWT token of the user to sign out. Identifies the user and the access token to revoke. [QS] `post_logout_redirect_uri`: Optional. Where to send the user after they have signed out. MUST be registered in the list of Redirect URIs for this App Registration. [QS] `state`: Optional. Pass in a state value that will be carried through and included in the redirect back to the `post_logout_redirect_uri` destination.	302 Redirect: GET [Redirect URI] &state=<Your State Value>

Secondary Endpoint Details

For information on the introspection and revocation endpoints, please refer to RFC 7662 and RFC 7009, respectively.

Code Flow Overview / Steps

User requests a secure page on the RP's website or app, and is not already signed in.
RP redirects to SSO authentication page.
IdP handles authentication (if the user is not already signed in) and authorization (if the user has not already granted consent and the grace period has not expired).
IdP redirects to the redirect_uri provided in the original request, providing a code in the URL which is good for 60 seconds.
RP makes a server-side request to the /openid/token endpoint, sending the code that was returned from the SSO redirect above.
IdP repsonds with an auth token, and optionally, an id token.
Optionally, IdP requests profile information via the /openid/userinfo endpoint, passing in the auth token as a bearer token for authenticating this request.

Differences from Standard OAuth Implementations

In this implementation, the Cloud SSO can only be used to verify that a user is signed in, and retrieve their profile information. It cannot be used to grant access to query the iMIS database or access the iMIS REST API.

Access tokens that are returned via this Cloud SSO service can be used to retrieve the user's profile information for as long as token is valid. Tokens can be refreshed using the refresh_token value. Tokens can be inspected using the introspection endpoint, and revoked using the revocation endpoint.

Because of this, the access token can be used and stored as the authentication mechanism at the third party (via cookies or session variables). Operations that are supported on access tokens include:

Extending the life of the access token by refreshing it (using the refresh_token value)
Revoking an access token (signing a user out)
Checking if an access token is valid (not expired or revoked)
Viewing the username that is associated with an access or refresh token