Skip to content

Commit

Permalink
Improve language consistency (#148)
Browse files Browse the repository at this point in the history
* Updated wording in the before-integrating section

* Updated wording in the integration section
  • Loading branch information
elenaschwan authored Jan 23, 2024
1 parent 6b6614f commit c7c96cb
Show file tree
Hide file tree
Showing 7 changed files with 28 additions and 33 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ review_in: 6 months

You’ll need to choose the level of authentication your service will require your users to have. You can find help on selecting an appropriate level of protection in the [guidance on using authenticators to protect an online service, also known as ‘GPG 44’](https://www.gov.uk/government/publications/authentication-credentials-for-online-government-services/giving-users-access-to-online-services#choosing-an-authenticator).

GOV.UK One Login uses ['Vectors of Trust'](https://datatracker.ietf.org/doc/html/rfc8485). Your service can use these Vectors of Trust to request the right level of authentication for your users to gain access to your service. You’ll include your vector in the query string as part of the authorisation request you make when you integrate with Authorization Code Flow.
GOV.UK One Login uses ['Vectors of Trust'](https://datatracker.ietf.org/doc/html/rfc8485). Your service can use these Vectors of Trust to request the right level of authentication for your users to gain access to your service. You’ll include your vector in the query string as part of the request you make when you integrate with Authorization Code Flow.

GOV.UK One Login currently supports the following authentication levels, also known as ‘levels of protection’ in GPG 44.

Expand All @@ -35,10 +35,10 @@ GOV.UK One Login currently supports the following authentication levels, also kn
</tbody>
</table>

You'll include your level of authentication in your authorisation request.
You'll include your level of authentication in your request to the `/authorize` endpoint.

Once you have chosen your level of authentication, you'll need to [choose the level of identity confidence][integrate.choose-level-of-confidence] if your service needs identity assurance.
Once you have chosen your level of authentication, you'll need to [choose the level of identity confidence][integrate.choose-level-of-confidence] if your service needs identity proving.

If your service does not need identity assurance, you can move on to [generate a key pair][integrate.generate-key-pair].
If your service does not need identity proving, you can move on to [generate a key pair][integrate.generate-key-pair].

<%= partial "partials/links" %>
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ review_in: 6 months

# Choose the level of identity confidence for your service

Using identity assurance is optional. If your service needs identity assurance, you’ll need to choose the level of identity confidence your service needs.
Using identity proving functionality is optional. If your service needs identity proving, you’ll need to choose the level of identity confidence your service needs.

You may need different levels of identity confidence at different points in your user journey. You can set the level of identity confidence your service needs for each request you make to GOV.UK One Login. Find out when and why to check someone’s identity in the [guidance about how to prove and verify someone's identity, also known as ‘GPG 45’](https://www.gov.uk/government/publications/identity-proofing-and-verification-of-an-individual/how-to-prove-and-verify-someones-identity).

GOV.UK One Login uses [‘Vectors of Trust’](https://datatracker.ietf.org/doc/html/rfc8485). Your service can use Vectors of Trust to request the right level of identity confidence for your users to gain access to the relevant parts of your service. You’ll include your vector in the query string as part of the authorisation request you make when you integrate with Authorization Code Flow.
GOV.UK One Login uses [‘Vectors of Trust’](https://datatracker.ietf.org/doc/html/rfc8485). Your service can use Vectors of Trust to request the right level of identity confidence for your users to gain access to the relevant parts of your service. You’ll include your vector in the query string as part of the request to the `/authorize` endpoint you make when you integrate with Authorization Code Flow.

<table class="tg">
<thead>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ review_in: 6 months

# Choose which user attributes your service can request

Your service can request certain user attributes. To do this, you need to choose which ‘scopes’ or ‘claims’ your service will use and include these when you make your authorisation request.
Your service can request certain user attributes. To do this, you need to choose which ‘scopes’ and ‘claims’ your service will use and include these when you make your request to the `/authorize` endpoint.

OpenID Connect (OIDC) scopes are identifiers your application uses during authentication to authorise access to a user’s attributes, such as an email address. Each scope returns a set of user attributes contained within it. OIDC calls this set of user attributes ‘claims’.

The user attributes and how you request them will depend on whether you are requesting authentication only, or authentication with identity assurance.
The user attributes and how you request them will depend on whether you are requesting authentication only, or authentication with a level of identity confidence.

<table class="tg">
<thead>
Expand All @@ -26,20 +26,17 @@ The user attributes and how you request them will depend on whether you are requ
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">You can only <a href=/before-integrating/choose-which-user-attributes-your-service-can-request/#choose-which-scopes-your-service-can-request><span>request user attributes using scopes</span></a>.</span></td>
</tr>
<tr>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">Authentication and <code>P1</code> identity assurance</span></td>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">You can only <a href=/before-integrating/choose-which-user-attributes-your-service-can-request/#choose-which-scopes-your-service-can-request><span>request user attributes using scopes</span></a>.</span></td>
</tr>
<tr>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">Authentication and <code>P2</code> (or higher) identity assurance</span></td>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">You can request user attributes using both claims and scopes (or either claims or scopes, depending on what your service needs).</span></td>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">Authentication and identity confidence</span></td>
<td class="tg-ycr8"><span style="font-weight:400;font-style:normal;text-decoration:none;color:#000">You can request user attributes using a combination of scopes and claims, depending on what your service needs.</td>
</tr>
</tbody>
</table>

You'll need to agree which scopes and claims you want to use when you [register your service to use GOV.UK One Login][integrate.register-your-service].

## Choose which scopes your service can request
`openid` is the only scope you must include. You can choose to include other scopes for your authorisation request depending on the user attributes your service needs.

`openid` is the only scope you must include. You can choose to include other scopes for your request to the `/authorize` endpoint depending on the user attributes your service needs.

You can find details of the scopes in the following table.

Expand All @@ -64,7 +61,7 @@ You can find details of the scopes in the following table.
<p><span style="font-weight: 400;">Required</span></p>
</td>
<td>
<p><span style="font-weight: 400;">OIDC authorisation requests must contain the <code>openid</code> scope value to indicate that an application intends to use the OIDC protocol.</span></p>
<p><span style="font-weight: 400;">OIDC requests to the <code>/authorize</code> endpoint must contain the <code>openid</code> scope value to indicate that an application intends to use the OIDC protocol.</span></p>
<br />
<p><span style="font-weight: 400;">This will return the <code>sub</code> claim, which uniquely identifies your user.</span></p>
</td>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ review_in: 6 months

# Create a configuration for each service you’re integrating

GOV.UK One Login is an OpenID Connect (OIDC) provider. An OIDC ‘relying party’ is an app that outsources its user authentication function to an identity provider, which in this instance is GOV.UK One Login.
GOV.UK One Login is an OpenID Connect (OIDC) provider. An OIDC ‘relying party’ is a client application that outsources its user authentication function to an identity provider, which in this instance is GOV.UK One Login.

To interact with GOV.UK One Login, you must first [register each of your services with GOV.UK One Login as a relying party][integrate.register-your-service]. You need to do this for each of the services that you want to integrate with GOV.UK One Login.
To interact with GOV.UK One Login, you must first [register each of your services with GOV.UK One Login][integrate.register-your-service]. You need to do this for each of the services that you want to integrate with GOV.UK One Login.

Part of the service’s configuration is the `client-id`, which is a unique identifier that GOV.UK One Login uses to identify your services. Each service should have a distinct `client-id`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,7 @@ review_in: 6 months

GOV.UK One Login is an OpenID Connect (OIDC) provider.

You must first register your service with GOV.UK One Login as a ‘relying party’ before being able to interact with GOV.UK One Login. You need to do this once for each of your services in the integration environment and the production environment.

An OIDC relying party is an app that outsources its user authentication function to an identity provider, which in this instance is GOV.UK One Login.
You must first register your service with GOV.UK One Login before being able to interact with GOV.UK One Login. You need to do this once for each of your services in the integration environment and the production environment.

## Register your service to use GOV.UK One Login

Expand Down Expand Up @@ -60,7 +58,7 @@ To update your service’s details with GOV.UK One Login, you need to send an em

## Progress your application to integrate with the integration environment

Once the GOV.UK One Login team has registered your service, you are now a relying party for GOV.UK One Login.
Once the GOV.UK One Login team has registered your service, you’ll receive a confirmation email.

The next step before you can use the integration environment is to [integrate with GOV.UK One Login][integrate.integrate].

Expand Down
Loading

0 comments on commit c7c96cb

Please sign in to comment.