Authenticating with OpenID Connect for beginners

This is a pretty simplified explination, but should get you going. Better resources may be available elsewhere.

Supported OIDC scopes

Four scopes are currently supported:

• openid: Required for authentication
• profile: Username and Display name
• email: User email
• groups: Includes a list of attributes related to the user, you usually won't need these
• owner: The user owns the app (probably you)
• userwhitelisted: The user has an app whitelist, and your app is on the list

Automatic

Most OIDC clients allow automatically configuring themselves from the discovery endpoint or issuer url. The discovery endpoint is at https://auth.stemk12.cc/.well-known/openid-configuration, and the issuer url is at https://auth.stemk12.cc. Most OpenID Connect libraries should automatically configure themselves using either the discovery endpoint URL, or the issuer URL.

Here is a list of available endpoints, keep in mind not all of these may be required by your client:

• Issuer URL: https://auth.stemk12.cc
• Discovery endpoint: https://auth.stemk12.cc/.well-known/openid-configuration
• Authorization URL: https://auth.stemk12.cc/apps/auth
• Token URL: https://auth.stemk12.cc/apps/token
• Userinfo URL: https://auth.stemk12.cc/apps/userinfo
• JWKS URL: https://auth.stemk12.cc/apps/jwks

You may need to look up your OIDC libraries redirect url and set it in your app.

Manual

1. Create an app

If you are seeing this, chances are, you already have! Now that you have an application, you should set the redirect url to the callback url for your application. This will be redirected to when a user accepts/denies the authorization. You should also set the launch url to the dashboard/home page of your site.

2. Redirect users

On your login page there should be a button that redirects users to the auth endpoint. The redirect should include your client id, redirect url, response type (always code for now), and scopes.
An example redirect url would be https://auth.stemk12.cc/apps/auth?client_id=your_client_id&redirect_uri=https%3A%2F%2Fexample.com%2Flogin%2Fcallback&response_type=code&scope=openid+profile+email. The scopes parameter determines what data your app needs. You may find supported scopes here.

3. Get tokens

After a user authorises with your app, they will be redirected to your redirect endpoint with a code parameter. To get user data, you must get a token using this code. Send a request to POST https://auth.stemk12.cc/apps/token with this form body:

{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "your_redirect_uri",
    "code": "flow_returned_auth_code"
}

Remember that all fields except grant_type will need to be modified by your app

The response will look something like this:

{
    "access_token": "123456...",
    "id_token": "eyJhbGciOiJ...",
    "token_type": "Bearer"
}

4. Getting user data

4a. Userinfo

You can get user data from GET https://auth.stemk12.cc/apps/userinfo and including the access token in the Authorization header.

4a. ID Token

You may also get some user data via the ID token. The ID token is a JWT that includes some user data, but not as much as the userinfo endpoint. Use this when you need to send data to the client quickly, and do not want to wait for the extra userinfo request. You can decode it with a JWT library. You may also want to validate the token's signature. You can get the token signature from GET https://auth.stemk12.cc/apps/jwks to validate the token.