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.

Problem with Integration Testing in Entra ID

Our DEVL and NLE environments provide the ability for us to create test users, however there are issues with trying to use these in automated testing.

  • Conditional Access Policies will prevent users from logging in if they are not on a compliant device. As these users will be logging in from a GitHub ephemeral environment, this log in will fail.
  • NLE and DEVL users require MFA, meaning any automation will be required to integrate MFA as part of their process.
  • Generic test users 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. To overcome the above scenarios, we would have to reduce our Security and Governance practices.

We therefore cannot support teams to integrate automated testing with Entra ID.

Solution

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

Resources