govuk-one-login / tech-docs Goto Github PK

View Code? Open in Web Editor NEW

8.0 45.0 3.0 9.83 MB

Documentation for integrating with GOV.UK One Login

Home Page: https://docs.sign-in.service.gov.uk/

License: MIT License

Dockerfile 0.17% Ruby 1.58% Shell 0.19% HTML 91.72% JavaScript 3.62% SCSS 2.72%

digital-identity

tech-docs's Introduction

GOV.UK One Login technical documentation

This documentation is for government services that want to integrate with GOV.UK One Login to:

authenticate their users
verify their users' identity

Preview your documentation changes

To preview any changes and additions you have made to the documentation in a browser, clone this repo and use the Dockerfile in this repo to run a Middleman server on your machine without having to set up Ruby locally.

This setup has live reload enabled, which means your changes will be applied as you edit files in the source directory. The only exception to this is if you make changes to config/tech-docs.yml, you must stop and restart the server to see your changes in the preview. You can stop the server with Ctrl-C.

Run the helper script:

./preview-with-docker.sh

It may take a few minutes to build the docker container, particularly if it is your first time running the script. When the server has finished loading you should then see the following output in the terminal:

== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
== Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman"/usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

Making changes to content

To add or change content, edit the markdown in the .html.md.erb files in the source folder.

Although a single page of HTML is generated, the markdown is spread across multiple files to make it easier to manage.

A new markdown file is not automatically included in the generated output. If you add a new markdown file at the location source/agile/scrum.md, the following snippet in source/index.html.md.erb will include it in the generated output.

<%= partial 'documentation/scrum' %>

Including files manually like this enables you to specify the position they appear on the page.

The sections in the documentation are controlled by the use of markdown headers, not the file structure.

Images to be included in the docs are kept in source/images

In order to configure some aspects of layout, like the header, edit config/tech-docs.yml.

If you move pages around and URLs change, make sure you set up redirects from the old URLs to the new URLs.

Making changes to a diagram

Edit the draw.io files in the source/images/originals folder by installing and using the draw.io desktop app.

Use one draw.io file per diagram.

Installing the draw.io desktop app

Run the following commands to use the draw.io desktop app from the command line.

brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

Editing and publishing a diagram

Follow these steps:

Create and modify a diagram using draw.io.
Save the draw.io file to the source/images/originals folder.
Publish the diagram as a scalable vector graphic (SVG).
Save the SVG file to the source/images folder.

Useful commands

Update a diagram:

draw.io source/images/originals/top-level-technical-diagram.drawio

Generate SVG versions of the diagrams and save them to the source/images/originals folder:

draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

Linting the GOV.UK One Login Technical Documentation

This repository uses Vale and the GDS Tech Docs Linter ruleset.

Installing the linter on your local machine

You need to:

install Homebrew
install Vale

Linting with your code editor

Many code editors provide extensions or plugins for Vale which can raise errors as you update documentation. You will still need Vale installed on your local machine.

Linting with Vale Command Line Interface (CLI)

By default, Vale must be run from the same directory as this config file, unless the --config flag is provide with a path. To run the linter using Vale CLI:

In a terminal window, navigate to your repo.
Run vale sync to download the latest tech-docs-linter package and unzip this to your StylesPath listed in your config file.
Run the command vale . to lint the entire repo or provide a path to a directory to lint only that directory for example: vale ./source/go-live

Updating to the latest tech docs linter ruleset

If a new rule is added to the tech docs linter ruleset, you can upversion the package used by this repo when you're ready. A later version of the ruleset can be tested and added by:

Create a branch.
Update the package version number in the Vale config file.
Run vale sync to download and unzip the latest package.
Run vale ./source to test the linter.
Fix any changes new ruleset throws up (preferably one commit for each rule violation).
Raise a PR with the latest version number in the vale config file.

Code of conduct

Please refer to the alphagov code of conduct.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

tech-docs's People

Contributors

Stargazers

Watchers

Forkers

shehir12 philf999 pauldougan

tech-docs's Issues

Re: 'Search'

Problem with 'Search' (https://docs.sign-in.service.gov.uk/search/) logbook

Table formatting

Our tables have lots of this:

<span style="font-weight:400;font-style:normal;text-decoration:none;color:#000;background-color:transparent">...</span>

We should replace this with a class on the table element (or td, or whatever), or just some CSS rules, or whatever :-)

Consistent wording for talking about 'identity proving'

We need to come up with a consistent way of talking about identity. Currently we are using:

identity proving
identity proofing
identity assurance
identity verification
identity checking

Even though all options have valid reasons to be used, we need to ensure we are using them correctly and consistently, and understand the nuances around each.

Create a default issue template to structure information gathered

At the moment new issues have no structure and are free format.

We should add a simple template to help structure the issues so that we are able to understand user needs.

There must be some good examples elsewhere in use at GDS we can look at for inspiration

Error running ./preview-with-docker.sh on intel mac

I attempted to build and run the local Docker version of the tech docs using ./preview-with-docker.sh and received an error as follows:


[+] Building 1.0s (8/10)                                                                                                                     docker:desktop-linux
 => [internal] load build definition from Dockerfile                                                                                                         0.0s
 => => transferring dockerfile: 330B                                                                                                                         0.0s
 => [internal] load metadata for docker.io/library/ruby:3.2.3-bullseye                                                                                       0.4s
 => [internal] load .dockerignore                                                                                                                            0.0s
 => => transferring context: 2B                                                                                                                              0.0s
 => [1/6] FROM docker.io/library/ruby:3.2.3-bullseye@sha256:38996d67add73dab08c19918bf842367c7bb6974bcd47054c1db5fdb830eefb6                                 0.0s
 => [internal] load build context                                                                                                                            0.0s
 => => transferring context: 29B                                                                                                                             0.0s
 => CACHED [2/6] WORKDIR /usr/src/gems                                                                                                                       0.0s
 => CACHED [3/6] COPY ./Gemfile /usr/src/gems                                                                                                                0.0s
 => ERROR [4/6] RUN apt-get update && apt-get install -y nodejs                                                                                              0.5s
------
 > [4/6] RUN apt-get update && apt-get install -y nodejs:
0.247 Get:1 http://deb.debian.org/debian bullseye InRelease [116 kB]
0.298 Get:2 http://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
0.330 Err:1 http://deb.debian.org/debian bullseye InRelease
0.330   At least one invalid signature was encountered.
0.353 Get:3 http://deb.debian.org/debian bullseye-updates InRelease [44.1 kB]
0.392 Err:2 http://deb.debian.org/debian-security bullseye-security InRelease
0.392   At least one invalid signature was encountered.
0.436 Err:3 http://deb.debian.org/debian bullseye-updates InRelease
0.436   At least one invalid signature was encountered.
0.440 Reading package lists...
0.450 W: GPG error: http://deb.debian.org/debian bullseye InRelease: At least one invalid signature was encountered.
0.450 E: The repository 'http://deb.debian.org/debian bullseye InRelease' is not signed.
0.450 W: GPG error: http://deb.debian.org/debian-security bullseye-security InRelease: At least one invalid signature was encountered.
0.450 E: The repository 'http://deb.debian.org/debian-security bullseye-security InRelease' is not signed.
0.450 W: GPG error: http://deb.debian.org/debian bullseye-updates InRelease: At least one invalid signature was encountered.
0.450 E: The repository 'http://deb.debian.org/debian bullseye-updates InRelease' is not signed.
------
Dockerfile:10
--------------------
   8 |     COPY ./Gemfile /usr/src/gems
   9 |
  10 | >>> RUN apt-get update && apt-get install -y nodejs
  11 |
  12 |     RUN bundle install
--------------------
ERROR: failed to solve: process "/bin/sh -c apt-get update && apt-get install -y nodejs" did not complete successfully: exit code: 100

looks like the apt stage is blowing up

I am running an intel mac with Sonoma 14.3.1 and Docker Desktop 4.27.2 (137060)

Placeholder in code examples do not use any brackets

The style guide recommends to use brackets to indicate placeholder in code examples, and there is a question on whether each code example needs a section on what to replace the placeholders with.

Current code example:

Use this example to make a request, [replacing your example's placeholder values](link to the table of parameters)
GET /authorize?response_type=code
&scope=YOUR_SCOPES
&client_id=YOUR_CLIENT_ID
&request=YOUR_REQUEST_OBJECT
HTTP/1.1
Host: oidc.integration.account.gov.uk

There is a discussion on whether we need to change all our examples to look like this instead:

GET /authorize?response_type=code
&scope={YOUR_SCOPES}
&client_id={YOUR_CLIENT_ID}
&request={YOUR_REQUEST_OBJECT}
HTTP/1.1
Host: oidc.integration.account.gov.uk
In your request, replace:

{YOUR_SCOPE} with ...

{YOUR_CLIENT_ID} with ...

{YOUR_REQUEST_OBJECT} with ...

The 2 things to address are:

do we need to use brackets when using placeholders?
do we need to add a section after each example to spell out what to replace the placeholders with?

Provide the public key for JWT validation in the documentatiion

In the documentation on the Process your user’s identity information page it says:

"Our support team will give you the public key you must use to validate this JWT."

Given the key required is public I suggest that the key is placed in the technical documentation so that relying parties can self serve.

Something like:

Here is the public RSA key that you can use to validate JWTs in the integration environment

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0_FAKE_KEY_CAQ8AMIIBCgKCAEAlWqnlDNB3ltSVKNZs
5aYyOxbD2yJrxb7Msnn_FAKE_KEY_JltzsRbTd5CPBof7r80R0aELt9hjQwRit
-----END PUBLIC KEY-----

hmcts.net account access to Slack

I am an hmcts.net user doing some initial investigations and prototyping. I can get access to the integration environment, and join the mailing list, but I can't get access to Slack, and I have some questions I'd like to as there.

(When I try to join the Slack channel, I get an email with the subject "No account found", which says "It looks like there isn’t an account on UK Government Digital tied to this email address.")

Remove the manifest.yaml file which is a relic deplying to the defunct GOV.UK PaaS

@elenaschwan The repo still contains a manifest.yml file which was only required when deploying to GOV.UK PaaS.

The file should be removed to avoid any confusion

List third party libraries for use with GOV.UK One Login

Some teams have started to open source the code they use to interact with us.
I wonder if it's useful to review which of those we endorse and then list them.

Discovering something like this could save an RP a lot of time?

Current ones we're aware of:

maintainer	repository	license	framework	language
DFE-Digital	one-login-aspnetcore	MIT	ASP.NET	C#
SkillsFundingAgency	das-shared-packages	MIT		C#
GDS	relying-party-stub	MIT	com.nimbusds/oauth2-oidc-sdk	Java

Scope parameter in token response example

In Receive response for ‘Make a token request’
an example response is provided:

{
  "access_token": "SlAV32hkKG",
  "refresh_token": "i6mapTIAVSp2oJkgUnCACKKfZxt_H5MBLiqcybBBd04",
  "token_type": "Bearer",
  "expires_in": 180,
  "id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg"
}

This example doesn't include the scope parameter and the subsequent table doesn't indicate which parameters are expected ('required'). The table does, however, refer the reader back to the scopes documentation page.

If the scope is always returned from the /token endpoint we should update the example to include it. If it is not always returned, then we should update the table to indicate it is an optional parameter and describe the conditions under which the relying party should expect to receive it.

Upgrade to Ruby 3.3.1 to fix apple issues

Not yet released but noting this PR.

Currently 3.3.0 has build issues on Apples new Mac with the fancy processors.
Ruby are working on a fix, should be 3.3.1 soon.

Don't upgrade back to 3.3.0 until we've confirmed that's fixed and tested with the tech writers.

Remove redundant .secrets.baseline file

What

remove .secrets.baseline from the repo which seems to be redundant

Why

seems to be redundant and something to do with pre commit hooks

It's done when

its gone and nothing has been affected

If we don't do this

we will have irrelevant clutter in the repo