Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve language consistency #148

Merged
merged 2 commits into from
Jan 23, 2024
Merged

Improve language consistency #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
835f303
Updated wording in the before-integrating section
elenaschwan Jan 17, 2024
6d0362c
Updated wording in the integration section
elenaschwan Jan 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions source/before-integrating/choose-the-level-of-authentication.html.md.erb
View file
Open in desktop
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" %>
4 changes: 2 additions & 2 deletions source/before-integrating/choose-the-level-of-identity-confidence.html.md.erb
View file
Open in desktop
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
17 changes: 7 additions & 10 deletions source/before-integrating/choose-which-user-attributes-your-service-can-request.html.md.erb
View file
Open in desktop
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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit confused about this change - I thought authentication only could not use claims?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we don't offer P1 at the moment, Phil suggested to take that line out, and replace the P2 line with Auth + Identity, since you can only request scopes with auth, but with auth + identity you can choose scopes and/or claims.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, we stuck with confidence here, because we are describing the concept, however, I am thinking we probably want to stay consistent and actually change it to proving after all, as we are talking about the type of request, and we refer elsewhere to auth and auth+identity, which is bringing us back to the core reason for having this PR. Would that make more sense?

<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
4 changes: 2 additions & 2 deletions source/before-integrating/create-individual-configurations-for-each-service.html.md.erb
View file
Open in desktop
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
6 changes: 2 additions & 4 deletions source/before-integrating/manage-your-service-s-configuration.html.md.erb
View file
Open in desktop
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
Loading