About Aurora OIDC/OAuth2.0 SSO
OpenID Connect (OIDC) is an SSO implementation based on OAuth2. Refer to the official OpenID Connect specs for more information.
OIDC Quick Start
Common OpenID Connect terms:
- OP = OpenID Provider, also known as the Identity Provider (IDP)
- RP = Relying Party, also known as the Service Provider (SP)
OpenID Connect typically follows this workflow:
- User requests to sign in.
- User is redirected to OP’s sign-in URL, and OP redirects the user to the RP with an authorization code sent as a query parameter value.
- RP sends a back-channel request to the OP’s token API with the OP-provided authorization code to retrieve the ID and Access Tokens.
- The ID Token is retrieved from the token response and is parsed as a JSON Web Token (JWT).
- The JWT is validated and decoded. (JWT validation should follow the signature specified in the OpenID Connect specifications.)
- The JSON payload is retrieved from the JWT and is parsed for claims to be set to the user’s community profile.
- If a user profile endpoint is configured, an additional call is made to the endpoint passing the access token using Bearer Authorization. (OIDC feature supports both GET and POST requests to the user profile endpoint. This is configured within the Provider settings.)
- Claims returned from the user profile endpoint are parsed and set to the user’s community profile based on configured Claim Mappings.
- Community checks to see if the user already exists with the specified SSO ID; if so, the user signs in to an existing account; if not, a new account must be created.
- User resumes browsing Khoros Community in signed-in state.
OAuth 2.0 typically follows this flow:
- User clicks the sign-in/registration link or takes an action that requires sign-in.
- User is redirected to a Khoros endpoint that builds the IDP/OP's sign-in URL based on configured attributes and the user state (that is, the page they were on when they initiated sign-in), and then redirects the user to the built sign-in URL.
- User signs in or registers. If the app is not on the allow list, the user will be prompted to give access to the Aurora Community app.
- The user is redirected to a callback URL on Community and an authorization code is included in the request as a query parameter.
- Community reads the authorization code.
- Community makes a back-channel API call to the OAuth provider to exchange the authorization code for ID and access tokens.
- The ID Token is retrieved from the token response and is parsed as a JSON Web Token (JWT).
- Optionally, the access token is then passed using Bearer Authorization in a subsequent API call to obtain additional user attributes such as SSO ID, e-mail address, display name, etc.
- Community checks to see if the user already exists with the specified SSO ID; if so, the user signs in to an existing account; if not, a new account must be created.
- User resumes browsing Khoros Community in signed-in state.
Enable OIDC/OAuth 2.0 SSO for the Aurora Community
Before you begin setting up OpenID Connect SSO for Community, you must gather this information:
- Client ID
- Client Secret
- Authorization Endpoint URL
- Token Endpoint URL
- (OIDC only) Expected “Issuer” for JWT validation
- (OIDC only) JWKS URI pointing to sign-in keys
- Claims mapping to map the minimum Community profile attributes to claims returned by the Token Endpoint URL and/or User Info URL. The required attributes that must be mapped are:
- SSO ID
- Login Name
- Email Address
Note: When adding Claim Mapping during Provider Creation, the keys for the above values are “ssoid,” “login,” and “email,” respectively.
After you have gathered the information listed above, you must create a Provider within the Community.
Note: For a detailed description of all the OIDC/OAuth 2.0-related provider settings, review Aurora OpenID Connect/OAuth 2.0 setting descriptions.
To create a Provider:
- Go to Settings > System > Account > OIDC/OAuth Providers > Add Provider.
- For each tab, enter this information:
- Name: Used to more easily distinguish a given provider in the UI.
- ID: Used in the Community sign-in URL, sign-out URL, and callback URL to distinguish between each provider configuration. Check out the examples below to see how these URLs are constructed.
- Client ID: Determined by the app created in your OP.
- Client Secret: Determined by the app created in your OP.
- Authorization: Enter authorization URL, Response Type, and Scope.
- Token: Token endpoint URL, expected Issuer, and JWKS URI. In addition, claim mapping must be added either here. The required profile attributes mentioned above must be mapped to an associated claim for SSO to function properly. For example, if the “sub” claim will be used for SSO ID, beside Claim mapping (ssoid required), click Add Parameter. Then enter “ssoid” into the Key field, and “sub” into the Value field.
- User Info: Fill in if any claim mappings come from a user info endpoint. Insert the user info URL and add any claim mapping.
- Click Create.
After the provider has been created, you must define the registration and sign-in URLs so the Community knows where to direct users when they sign in.
To define the registration and sign-in URLs, see Configure SSO settings for the community.
When creating the app in the OP, you might be asked to specify a callback URL. The callback endpoint uses this format:
https://<communityhost>/t5/s/auth/oauth2callback/providerid/<providerid>
For example, if a Community at https://community.acme.com was configured with Provider ID “acme,” the URL would be:
https://community.acme.com/t5/s/auth/oauth2callback/providerid/acme
Note: If your Aurora community is configured for Reverse Proxy with Subdirectory, your endpoint paths are pushed up into the reverse proxy path similar to other URLs in your community.
Related topics: