Aurion OpenID Configuration Guide

Download PDF
Version Description Date
1.0 Initial version 02/12/2019

Introduction

Aurion offers OpenID Connect as one method of authenticating Self Service users.

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol. OAuth 2.0 defines mechanisms to obtain and use access tokens to access protected resources, but they do not define standard methods to provide identity information. OpenID Connect implements authentication as an extension to the OAuth 2.0 authorisation process. It provides information about the end user in the form of an id_token that verifies the identity of the user and provides basic profile information about the user.

Prerequisites

To configure OpenID you will need to provide the following:

Basic Configuration

  • application_id (also known as a client_id, although it is specific to the application being signed into, and there may be many of these within your tenant_id
  • tenant_id).

Azure Configuration

OpenID Configuration

OpenID Belt Configuration

You can configure OpenID on your web server using a Belt override to replace the login section in the env.config.js file, as shown below.

On the Web tab in Belt:

  1. Select the env.config.js file from the Override Template File
  2. Enter “login: [],” in the Search
  3. Enter the following text in the Replace field, replacing the <tenant_id> and <client_id> with your details:
    login: {
      message: '<span style="color: red;">Default message</span>',
      strategy: [
        {
          // open id connect implicit flow
          id: 'OID',
          method: 'openid',
          options: {
            issuerOpts: {
              issuer: 'https://login.microsoftonline.com/<tenant_id>/v2.0/',
              authorization_endpoint: 'https://login.microsoftonline.com/pfidentityservereuprod.onmicrosoft.com/oauth2/v2.0/authorize?p=b2c_1_localsignuporin',
              jwks_uri: 'https://login.microsoftonline.com/pfidentityservereuprod.onmicrosoft.com/discovery/v2.0/keys?p=b2c_1_localsignuporin',
            },
            clientOpts: {
              client_id: '<client_id>',
            },
            authOpts: {
              redirect_uri: 'http://localhost:3000/login/callback'
            }
          },
        },
      ],
    },

This override will be reapplied whenever Belt is updated.

OpenID Non-Belt Configuration

If your organisation doesn’t use Belt you can manually update the “login: [],” section of the env.config.js file with the text shown above.

Note that any changes you make to the env.config.js file will be overwritten when you upgrade Aurion, so you will need to make a copy of these changes and reapply them after upgrading Aurion.

Azure OpenID Configuration

The flowchart below provides an overview of the sign-in process when using OpenID with Azure:

Register an Application

You must first register an app with Azure, which will provide an Application ID for the application (Aurion), as well as enable it to receive tokens.

  1. Open Microsoft Azure.
  2. Search for “Azure Active Directory” in the search field at the top of the page then click that option:
  3. Click ‘App registrations’ from the Manage list on the left-hand menu, then click the ‘Register an application’ button.
  4. Follow the prompts to create a new application:
    • ‘Name’ is the application name and describes your application to end users.
    • Under ‘Supported account types’, select ‘Accounts in this organizational directory only’.
    • Provide the redirect URI. For web applications, this is the base URL of your app where users can sign in, e.g. http://localhost:3000. For public clients, (mobile and desktop), Azure AD uses the redirect URI to return token responses. Enter a value specific to your application, e.g. http://MyAzureApp.

Once you’ve completed registration, Azure AD will assign your app an Application ID, and a unique tenant identifier (the Directory ID). You need these values in the next sections, so copy them from the application page:

Metadata

OpenID Connect describes a metadata document that contains most of the information required for an app to perform sign-in. This includes information such as the URLs to use and the location of the service’s public signing keys. The OpenID Connect metadata document can be found at:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

The metadata is a simple JSON document. See the following snippet for an example:
{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

The snippet’s contents are fully described in the OpenID Connect website specification page (https://openid.net/).

Note that providing a tenant ID rather than common in place of {tenant} above will result in tenant-specific URIs in the JSON object returned.

If your app has custom signing keys as a result of using the claims-mapping feature, you must append an appid query parameter containing the app ID in order to get a jwks_uri pointing to your app’s signing key information. For example:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of 
https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Sign-in Request

When your web application needs to authenticate the user, it must direct the user to the /authorize endpoint.

The request must include the scope openid in the scope parameter.

The response_type parameter must include id_token.

The request must include the nonce parameter.

A sample request would look similar to:

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

At this point, the user is asked to enter their credentials and complete the authentication.

Additional Information

Aurion Configuration

Automatic Logon Parameters

Configure the following settings on the Automatic Logon Parameters screen (EC867_SSO):

  • Auto Logon Enabled = selected
  • Method = Use HTTP header authentication
  • HTTP Header Name = REMOTE_USER.

Security User Detail

The OS User Name field for employees accessing Self Service should be the email address they
use to authenticate against the Identity Provider.

Token Validation

You must validate the signature and verify the claims in the id_token per your app’s requirements. The Azure AD endpoint uses JSON Web Tokens (JWTs) and public key cryptography to sign tokens and verify that they are valid.

Sign-out Request

You must redirect the user to the end_session_endpoint for sign-out. If you fail to do so, the user will be able to reauthenticate to your app without entering their credentials again, because they will have a valid single sign-on session with the Azure AD endpoint.

You can simply redirect the user to the end_session_endpoint listed in the OpenID Connect metadata document:

GET https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Single Sign-out

When you redirect the user to the end_session_endpoint, Azure AD clears the user’s session from the browser. However, the user may still be signed in to other applications that use Azure AD for authentication. To enable those applications to sign the user out simultaneously, Azure AD sends an HTTP GET request to the registered LogoutUrl of all the applications that the user is currently signed in to. Applications must respond to this request by clearing any session that identifies the user and returning a 200 response. If you wish to support single sign-out in your application, you must implement such a LogoutUrl in your application’s code.

You can set the LogoutUrl from the Azure portal by following these steps:

  1. Navigate to the Azure portal.
  2. Choose your Active Directory by clicking on your account in the top right corner of the page.
  3. From the left hand navigation panel, choose Azure Active Directory, then choose App registrations and select your application.
  4. Click on Settings, then Properties and find the Logout URL text box.

Token Acquisition

Many web apps need to not only sign the user in, but also access a web service on behalf of that user using OAuth. This scenario combines OpenID Connect for user authentication while simultaneously acquiring an authorization_code that can be used to get access_tokens using the OAuth Authorization Code Flow.

To acquire access tokens, you need to modify the sign-in request from above in the following way:

// Line breaks included for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e  // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345   // Your registered Redirect Uri, url encoded
&response_mode=form_post                      // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F  // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                  // Any value, provided by your app
&nonce=678910                                 // Any value, provided by your app

A successful response, sent to the redirect_uri using response_mode=form_post, looks like:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=3000

Error responses may also be sent to the redirect_uri so the app can handle them appropriately, e.g.:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication

Further Configuration

You can optionally further configure your endpoint by going to your Azure Active Directory, selecting your app, then going to the ‘Authentication’ tab on the left.

2019-12-02T10:29:32+10:00

Leave A Comment