Single Sign-On (SSO) with OpenID Connect (OIDC)

Authorization Flow

1. User Redirects to Authorization Endpoint

The client application directs the user to the authorization server’s authorization endpoint:

GET https://app.401go.com/api/o/authorize
?response_type=code
&client_id={CLIENT_ID}
&redirect_uri={REDIRECT_URI}
&scope=openid
&state={OPTIONAL_STATE}

By default, the openid scope only grants access to employees. If you want to use SSO for a company admin then you'll need to include the company:read scope in addition to the openid scope:

...
&scope=openid company:read
...

2. User Authenticates

The user logs in and consents to the requested scopes.

3. Authorization Code is Issued

If successful, the authorization server redirects the user to the specified redirect_uri with an authorization code:

{REDIRECT_URI}?code={AUTHORIZATION_CODE}&state={OPTIONAL_STATE}

4. Exchange Authorization Code for Tokens

The client exchanges the authorization code for an ID token and access token by making a POST request to the token endpoint:

POST https://app.401go.com/api/o/token
?grant_type=authorization_code
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&code={AUTHORIZATION_CODE}
&redirect_uri={REDIRECT_URI}

The response contains:

{
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3600.0,
    "token_type": "Bearer",
    "scope": "openid",
    "refresh_token": "<REFRESH_TOKEN>"
    "id_token": "<ID_TOKEN>",
}

5. Retrieve User Information (Optional)

User details can be fetched from the user info endpoint:

GET https://app.401go.com/api/o/userinfo
Authorization: Bearer <ACCESS_TOKEN>

The response typically includes:

{
    "sub": "lrio5has",
    "role": "participant",
    "name": "John Doe",
    "company_name": null,
    "dob": "1995-04-15",
    "email": "[email protected]",
    "phone_number": "1234567890"
}

• Possible role's - participant, company_admin
• company_name will be a string value if role is company_admin, and null otherwise
• dob will be a string value if role is participant, and null otherwise

Error Handling

If an error occurs, the authorization server returns an error response with an error parameter indicating the issue. Common errors include:

• invalid_request – Missing or invalid parameters.
• unauthorized_client – Client is not authorized for this request.
• invalid_grant – Invalid authorization code.