Skip to main content

Application Registrations (SSO)

Best Practices

Client Secrets

Storing your new secret securely

Once we have sent you your new secret, it is essential that you store your new secret in a secure location such as

  • In a secure vault such as Azure Key Vault or AWS (Amazon Web Services) Secrets Manager
  • In a GitHub or Azure DevOps Secret variable

What not to do with your new secret

Do not store or share your secret anywhere else such as

  • Any type of document such as spreadsheets or word processor documents
  • Document/Content Management Systems such as SharePoint
  • Send via email
  • Locally on your computer

Problems, guidance, or incidents

If you lose, misconfigure, or accidentally expose your secret in any way or are unsure around the guidance above, contact the IDAM team (IDAMTeam@justice.gov.uk) immediately. We will revoke the old secret and generate a new one for you or provide one-to-one guidance on next steps.

Renewing credentials

Self Service Renewal

If you are assigned as an Owner of an App Registration, you are able to renew your credentials without requiring contact with the IDAM team.

Checking for Ownership

To check if you are able to, follow these steps

  • Go to https://portal.azure.com/
  • Sign in with your identity
  • In the search bar, type Microsoft Entra ID and select the feature
  • Click on App registrations
  • In the list of Owned applications, you will be able to see your App Registration
  • Click the App Registration to open the dashboard
  • Under Manage, select Certificates & secrets
  • The button New client secret should be available for you to click

Updating your Credential

  • Go to https://portal.azure.com/
  • Sign in with your identity
  • In the search bar, type Microsoft Entra ID and select the feature
  • Click on App registrations
  • In the list of Owned applications, you will be able to see your App Registration
  • Click the App Registration to open the dashboard
  • Under Manage, select Certificates & secrets

Client Secret

  • Click on Client secrets
  • Click the button New client secret
  • In the pop up
    • Enter a description
    • Choose an expiry period (up to 2 years)
  • Copy the new secret Value and store in a secure place (this will only be visible this one time)
  • When possible, ensure any old secrets are removed from your App Registration

Client Certificate

  • Click on Certificates
  • Click the button Upload certificate
  • In the pop up
    • Upload your new .cer, .pem or .crt certificate file
    • Enter a description
  • Click Add
  • When possible, ensure any invalid certificates are removed from your App Registration

ServiceNow Client Secret Renewal

To renew a Client Secret used by your integration, you can make a request to the IDAM team via the Entra Id - Renew App Registration Certificate / Secret.

You will need to provide the following details

Field Description
Application Name Name of your application this secret is assigned to.
Application ID Also referred to as your Client ID, this is the ID used in your integration to identify itself.
Environment Is this for the Entra DEV, NLE or LIVE environment.
Please select what you would like to update Select Certificate.
Old Secret Expiry Date This will allow you to have two valid secrets while you update your integrations. We will remove the old secret on this date.

This will then be assigned to the IDAM team to schedule and communicate when we will complete the request for you.

Once we have generated a new Secret, we will send the requestor of the catalogue item an email with a secure link to access the new credentials. This link will expire after an hour.

You should store this new value in a secure vault once received and remove any traces of it from your computer systems.

Entra Id - Renew App Registration Certificate / Secret

ServiceNow Certificate Renewal

To renew a Client Certificate used by your integration, you can make a request to the IDAM team via the Entra Id - Renew App Registration Certificate / Secret.

Ensure you have exported your Public Key (.cer, .pem, .crt) ready to attach to the ServiceNow request.

You will need to provide the following details

Field Description
Application Name Name of your application this certificate should be assigned to.
Application ID Also referred to as your Client ID, this is the ID used in your integration to identify itself.
Environment Is this for the Entra DEV, NLE or LIVE environment.
Please select what you would like to update Select Certificate.
Attachements Add your certificate here (.cer, .pem, .crt).

This will then be assigned to the IDAM team to schedule and communicate when we will complete the request for you.

Entra Id - Renew App Registration Certificate / Secret

Integration Testing with Entra ID

Problem Statement

As a Developer, I want to create end to end integration tests for my application that integrates SSO with Entra ID and have access to test users in a Dev and Staging environment to test against in my GitHub PR Pipelines.

What can you test

The IDAM team can provide you with a set of test users in our DEVL environment. These can be used in your automated testing.

To request test users and access to automated testing you should raise a Demand with the Demand team for the IDAM team to create the users and configure the Application Registration ready for use.

We do not allow automated testing against our NLE and LIVE environment.

Reasons for not allowing automated testing in NLE and LIVE

Due to security and governance standards, we cannot allow testing in these environments for the following reasons.

  • Conditional Access Policies will prevent users from logging in. As these users will be logging in from a GitHub ephemeral environment, this log in will fail.
  • NLE and LIVE users will require certain compliance rules preventing access in an automated way.
  • Generic test users in NLE and LIVE pose an issue where passwords would be shared among multiple people and could be disabled or changed at any moment breaking path to live in pipelines.

Due to these limitations, it is not recommended to include the Entra ID log in flow as part of your integration tests in any environment apart from DEVL. To overcome the above scenarios, we would have to reduce our Security and Governance practices.

Solution for testing in NLE and LIVE

We recommend you use a Mock OAuth Provider as part of your pipelines. This will enable you to have full control over Authorisation test scenarios during your testing and a faster feedback loop.

Many existing integrations follow this pattern, an example can be found below by OPG in their Sirius codebase which integrates with Entra ID.

https://github.com/ministryofjustice/opg-sirius/tree/main/mock-oauth-provider

Role-based access control (RBAC)

App Roles

When considering using Entra ID to provide Authorisation as well as Authentication, we prefer using App roles to manage permissions.

Entra ID Application Registrations have the ability for you to implement RBAC rules via Application Roles and assign Groups of users or individual users to them.

Within the App roles option of your Application Registration, you can create custom App roles for each RBAC role type and link each Role to a Security Group. For example

Role Name Security Group
Administrator eucs-idam-wordpress-administrators
Writer eucs-idam-wordpress-writers
Approver eucs-idam-wordpress-approvers

When a user authenticates with Entra ID and is passed back to your application, Entra ID will check the user against these roles and pass a roles claim via the authentication token for your application to parse.

The Security Group(s) assigned to each Role can be any of the following

  • Dynamic Security Group
  • IDAM Team Managed Static Security Group
  • Self Service Security Group

Security Groups and types available are explained in the Entra Security Groups documentation.

For implementation guidance using App roles in your application, follow the Microsoft guidance in the links below.

Token Lifetime Policy

We cannot offer custom policies to change the default Token Lifetime Policy (1 hour) within our tenant. Doing so would reduce our security posture to adversary-in-the-middle (AiTM) phishing attacks and token theft.

e.g. If we changed this policy to 8 hours and a token was compromised, we would not be able to revoke the users session until this period has expired.

You should therefore implement refresh token functionality into your application. This will allow you to refresh the token before expiry and prevent the user to have to reauthenticate.

For guidance on using refresh tokens, see these following links

Resources