Choosing an authentication component

Because CIS2 Authentication conforms to the open standard Open ID Connect (OIDC), there are a number of off-the-shelf authentication components that could make your integration easier.

Depending on your situation, you might benefit from:

• identity providers with OIDC federation capabilities
• OIDC client libraries

If you're using an off-the-shelf identity provider (IdP) for your application's authentication framework, it might include capabilities to integrate with an external OIDC server, also referred to as an 'OIDC Provider'.

Examples of IdPs that do this include:

• Microsoft Entra
• AWS Cognito
• Okta
• Auth0

This approach is most applicable to web applications, especially cloud-based web applications.

Rather than having to hand-code your CIS2 Authentication integration, you would configure it within your IdP by providing details such as the location of the OIDC configuration document, as explained in Discovery.

However, CIS2 Authentication has some specific requirements that you need to be aware of. Some are essential, others are only needed when, for example, JWKS endpoints need to be supported.

You should consider whether your chosen (or incumbent) component offers sufficient control over the authentication process. You're also strongly encouraged to raise deficiencies in your chosen products with the relevant providers, such as AWS customer managers for issues with Cognito.

Additional query string parameters

The ability to add optional parameters to the authentication request is extremely important. Some components do not support all optional parameters, even though they are part of the OIDC specification.

For example:

• authentication behaviour modification - required to be able to request "SSO" type behaviour, or not: 
  • prompt parameter
  • max_age parameter
• ACR values - used to indicate what level of authentication is acceptable and should be offered to the user:
  • acr_values parameter

ID token inspection

For example examination of the auth_time, and rejection of the token if it is too old.

This is required to ensure that any authentication requirement directives have been followed, and check that the initial authentication request was not tampered with. A malicious actor could remove the prompt=login or max_age value to allow an existing session to be used, and if you do not check this value then this will go unnoticed. 

ID token availability

For example the ability to receive the CIS2 Authentication ID token in the application code. 

This is most often required so that you can then exchange the CIS2 Authentication ID token for an API platform access token, using separate authentication and authorisation.

Support for better client authentication

Most implementations allow the use of client id and client secret for an OIDC client to authenticate against the OIDC provider. However, this form of client authentication, while simple, is less secure than others, and does not allow for seamless rollover of client credentials.

Not all components will allow the preferred "private_key_jwt" client authentication with client JWKS endpoint. See detailed guidance on this topic.

Sometimes, it may be possible to work around the deficiencies of a product. 

For example, for AWS Cognito, which doesn't currently support the query string parameters, or JWKS endpoint, one can use a Lambda process to effect change on the authorize URL, or JWKS endpoint provision. See an example.

If you've built your own authentication framework, or you're using an off-the-shelf identity provider but it doesn't provide suitable federated OIDC capabilities for integrating it with CIS2 Authentication, you could still benefit from using an OIDC client library.

These client libraries, sometimes referred to as 'Relying Party' libraries, hide some of the code that's required to integrate with an OIDC server.

They come in a variety of programming languages, including Python, C# and Java.

Some libraries are certified by the OpenID Foundation.

Other libraries are not certified, but are easily found via a suitable internet search.

Make sure you look for client libraries - there are plenty of implementations of OIDC servers out there, but you need an OIDC client.