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.

Credentials

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 and Access Packages

Overview

As well as using Entra ID for your Authentication, you can also take advantage of App Roles and Access Packages to manage your integrating applications Authorisation.

Managing users this way over Security Groups or custom Authorisation layers in your application have multiple advantages

JML processes will automatically remove access from your application when a user is deleted within Entra ID
Approvals are handled through the Microsoft My Access portal requiring user authentication before assignment
Audit trail of access requests
Automated Access Reviews to ensure users have the right access
Further Governance, i.e., those that do not have the Entra Role “Identity Governance Administrator” or assigned either Delegation and roles in entitlement management - Microsoft Entra ID Governance will not be able to add members to group without adding members to the access package
Integration with wider Azure and Entra permissions and groups for automated assignment (future)

Access Packages sit under the Microsoft Entitlement Management offering. To learn more about Entitlement Management, Access Packages and App Roles, use the following links

How App Roles works

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 Access Package. For example

Role Name	Access Package
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 is a part of the Access Package and pass a roles claim via the authentication token for your application to parse.

How Access Packages works

For a detailed overview of Access Packages and how they are used to manage user access to resources, see Request process and email notifications in entitlement management.

The IDAM Team will provide you with unique urls you can give to your users so that they can request access to the resource.

A user that needs access to a role for your application can submit an access request. When a request is approved, a process begins to assign the user access to the role for that application in the access package. The following diagram shows an overview of the process and the different states:

If you’re an approver, you’re sent email notifications when you need to approve an access request. You also receive notifications when an access request has been completed. You’re also sent email notifications that indicate the status of your request if you’re a requestor.

Example email

If you have chosen to have Access Reviews for your Access Package, you will be sent regular emails to review each user within the Access Package. This can help maintain Just Enough Access for users in your system. For more information on how this process works, please see What are access reviews? - Microsoft Entra ID Governance.

Requesting App Roles and Access Packages

You will need to raise a Demand through the existing demand process for this option. This will be triaged by the Demand Team and sent through to the IDAM Team to action.

The link to the demand process can be found at Technology Services New Demand Request

You should provide the following information with the demand request.

List of Application Roles

Provide a list of required Application Roles in a list providing the information for each as outlined below.

Field	Description	Example
Display Name	Display name for the App role that appears, for e.g. in the assignment and consent experiences.	e.g. `Admin`, `Write`, `Read`, `ReadWrite`, etc
Role Value	Specifies the value which will be included in the “roles” claim of a token identifying a user or app which has been granted this app role.	e.g. `Users.Admin`, `Users.Write`, `Users.ReadWrite`
Description	App role help text that appears in the app assignment and consent experiences.	e.g. `Allows users Administrator rights over the Blog`.

Access Package Details

Field	Description	Example
OrganisationName	Your organisation name.	`Justice Digital`, `Tech Services EUCS`, `CICA`
DepartmentName	Your departments name.	`LAA`, `OPG`, `IDAM`
ApplicationName	Your application name.	`ServiceNow`, `Slack`
Access Package Approvers	A list of people who will be responsible for the approval of access to the packages. This should ideally be more than 2 people.	List of `@justice.gov.uk` addresses.
Require Access Reviews?	Does the requestor want to enable Access Reviews for their Access Package. If yes, complete the additional table below. For more information, see What are access reviews? - Microsoft Entra ID Governance	`ServiceNow`, `Slack`

Access Review Details (optional)

Field	Description	Example
Access Package Reviewers	A list of people who will be responsible for the review of users who have access to the packages. This should ideally be more than 2 people.	List of `@justice.gov.uk` addresses.
Review frequency	How often do you want to review users access? This should be in days with a minimum of 30 days up to 365 days.	`365 days`

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

EUCS IDAM Team Shared Inbox