OpenId-Connect SSO - Administrator Guide

Abstract

Primer

How to configure ShoutCMS to be an OpenId-Connect (OIDC) OP/IdP to allow ShoutCMS to provide Single Sign On logins to a RP.

Audience

Administrators of a ShoutCMS site with access to the admin console

Terminology and Abbreviations

Abbreviations

Terminology

Actors

What is OIDC

OpenID Connect (OIDC) is a secure identity layer built on top of the OAuth 2.0 protocol. While OAuth 2.0 is about authorization (giving an app permission to do something), OIDC is about authentication (proving who a user is).

When you see a button that says "Sign in with Google" or "Log in with Apple" or "Log in with ShoutCMS" you are looking at OIDC in action.

How OIDC works

OIDC is basically a "vouching" system for the internet. Instead of making a brand-new username and password for every site you visit—like a news website—you can just use an account you already have, like ShoutCMS. When you click that "Sign in with ShoutCMS" button, ShoutCMS handles the security check. Once it confirms who you are, it tells the news site, "This person is verified," and shares just enough info (like your name) to get you started.

Shoutcms and OIDC

ShoutCMS supports SSO by being an Identity Provider / OpenID Provider for OpenId-Connect (OIDC) https://openid.net/connect/

Technical Details

The ShoutCMS OIDC Implementation currently supports:

• The "Authorization Code Flow" - gold standard
• id_token signing using the RS256
• "prompt" requests (none, login, consent, select_account)
• claims via the scopes (email, profile, address, phone, company, company_name, roles, member_id)
• the userinfo and revocation endpoints

How ShoutCMS OIDC works

ShoutCMS OIDC can be setup to work in two main ways: originating on the [RP] website OR originating on the [OP] ShoutCMS website.

User OIDC Authentication Login Processes

User login process originating at [RP]

1. [user] visits the [RP] website
2. [RP] (optional) if it supports the prompt functionality [RP] can attempt to silently login user. If silent login works process continues on the step 14.
3. [RP] checks if [user] is logged in. If [user] is logged in process continues on step 15
4. [user] will click a link or button to login on the [RP] website
5. [RP] will redirect the [user] to the [OP] login page
6. [OP] will determine if [user] is already logged into the [OP] site. If the [user] is logged in process continues at step 8. If the [user] is not logged in process continues at step 6.
7. [OP] will show the login page
8. [user] will login to [OP]
9. [OP] will show a page asking user to approve giving profile information to the [RP] (If you want to auto approve and allow contacts to skip this step since the app you are connecting to is trusted you can contact ShoutCMS customer care and they can help you.)
10. [user] will approve [OP] giving profile information to [RP]
11. [OP] the user will be redirected back to {{clientapp}} via the redirect url
12. [RP] receives callback at redirect_url and verify that the request is from [OP]
13. [RP] (optional) if user does not exist in [RP] user can be created
    
14. [RP] logs in user
15. [user] uses [RP]

User login process originating at [OP]

1. [user] visits the [OP] website
2. [user] clicks the login link or goes to a page requiring login
3. [OP] checks if [user] is logged in. If [user] is logged in process continues on step 6
4. [OP] will show the login page
5. [user] will login to [OP]
6. [OP] will redirect [user] to the user dashboard page or page requiring login
7. [user] can click a link on that page which goes to the [RP]
8. process continues at "User login process originating at [RP]" step 1

User logout process (optional)

1. [user] logs out of the [RP]
2. [RP] revokes the OpenId-Connect login

Configuration

1. Configure ShoutCMS OP/IdP Configuration
2. Configure Client App RP Configuration

ShoutCMS OP/IdP Configuration

1. Login to ShoutCMS admin console
2. Configure API OAuth Public Keys
3. Configure OAuth Scopes
4. Configure OAuth Client

Configure API OAuth Public Keys

1. goto settings > Integrations / API > API OAuth Public Keys
2. If public key already exists you can skip to step 2. If a public key does not exist generate one using the "Generate API Public Key" button.
3. If the OIDC client does not support public key validation OR the OIDC client supports /.well-known/openid-configuration and  /.well-known/openid-configuration/jwks.json you can skip this step. Otherwise, record the public key for use in your OIDC client. If you lose this public key you can just visit the API OAuth Public Keys settings page and click on the public key you wish to see/record. NOTE: some [clientapp] do not use the public key to validate the oidc sso login
   

Configure OAuth Scopes

1. goto settings > Integrations / API > API OAuth Scopes
2. enable those scopes which you want the API OIDC clients to be able to request during the OIDC flow (note: you need to have at least one OIDC scope enabled) See appendix
3. Save

Configure OAuth Client

1. goto settings > Integrations / API > API OAuth Client
2. you add a new OIDC client configuration by using the "Add API Client" button.
   1. give the client a memorable name
   2. enter the redirect uri to which shoutcms will redirect OIDC responses to (note: if you don't know this yet you can always change this later.)
   3. If you want to restrict the api client to run from the scope a particular user/contact you can browse for a user here. In most OIDC you should leave this blank. IE. This is used typically for server to server OAuth2 api clients.
   4. Choose the grant types you wish to support. These enable the various OAuth2/OIDC flows.
      In order to use OIDC you should enable the Authorization Code grant.
   5. Save
3. Record the client_id and you NEED to record the client secret otherwise you will need to regenerate it. You can view; update; or generate a new client id and secret for an API Client by visiting the API OAuth page in settings and client on it.
   

Client App RP Configuration

Every Client App has its' own configuration. See its documentation on how to configure the OpenId-Connect client. However all Client App's will require at least the client id and client secret. The Client App will then the OpenId-Connect Config Url. Or the Client App it will require the OAuth2 Authorize Endpoint and OAuth2 Token Endpoint. Finally The Client App will optionally want a scope to be entered.

Appendixes

appendix i - Configuration Values

-----BEGIN PUBLIC KEY----- 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAA
-----END PUBLIC KEY-----

appendix ii - OAuth2 Scopes

OAuth2 Scopes control what user details can be requested during the login process

appendix iii - Example OpenId-Connect Configuration file

{
    "issuer": "https://example.com",
    "authorization_endpoint": "https://example.com/_/oauth/authorize",
    "token_endpoint": "https://example.com/_/oauth",
    "userinfo_endpoint": "https://example.com/_/oauth/userinfo",
    "revocation_endpoint": "https://example.com/_/oauth/revoke",
    "jwks_uri": "https://example.com/.well-known/openid-configuration/jwks.json?client_id=aaaaaaaaaa",
    "response_types_supported": [
        "code",
        "token",
        "token",
        "id_token",
        "code token",
        "code id_token",
        "token id_token",
        "code token id_token"
    ],
    "subject_types_supported": [
        "public"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "scopes_supported": [
        "email",
        "profile",
        "address",
        "phone",
        "company",
        "company_name",
        "roles",
        "member_id",
        "openid"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic"
    ],
    "claims_supported": [
        "name",
        "family_name",
        "given_name",
        "preferred_username",
        "profile",
        "picture",
        "website",
        "updated_at",
        "email",
        "email_verified",
        "formatted",
        "street_address",
        "locality",
        "region",
        "postal_code",
        "country",
        "phone_number",
        "company_name",
        "company_url",
        "company_description",
        "company_logo",
        "https://oidc.shoutcms.net/company_name",
        "https://oidc.shoutcms.net/roles",
        "https://oidc.shoutcms.net/member_id"
    ],
    "grant_types_supported": [
        "authorization_code"
    ]
}