ukhomeoffice / keycloak-theme-govuk

A Keycloak theme using GOV.UK Template and Elements

keycloak-theme-govuk

A Keycloak theme using GOV.UK Template and Elements.

• Using
• Developing
  • Building
  • Local Keycloak server
  • Testing Keycloak e-mails
• Releasing

Using

This theme has been deployed to the UK Home Office hosting platform Keycloak Docker container. To use it in your Keycloak realm:

1. Sign into your realm's admin console.

   

2. Go to the “Themes” tab in “Realm Settings”

   

3. Select “govuk” as your login theme, and click on “Save”

   

The theme will now be used for all Keycloak log in screens on your realm - including logging in to the admin console. If you sign out, you should see the GOV.UK themed log in screen.

Developing

Building

The theme can be built using the following commands:

$ npm install
$ npm run build

The theme will then be built at /govuk, ready for use in the local Keycloak server.

Local Keycloak server

A local Keycloak server for developing and testing the theme is available as a Docker container. Ensure that the latest version of the docker container is used in docker-compose.yml. The latest version can be found at:

https://quay.io/repository/ukhomeofficedigital/keycloak?tab=tags

To bring up the server, make sure you’ve installed and started Docker Community Edition, then use the following commands:

$ npm install
$ npm run build
$ docker-compose up

The Keycloak server will now be available on http://localhost:8080. You can log into the Administration Console using “admin” as both username and password.

To enable the GOV.UK theme in the local Keycloak server, follow steps 2 and 3 in the “Using” section above.

You will now see the GOV.UK theme when logging into the local Keycloak server. Changes made to the theme files in /govuk will be visible on the local Keycloak server when you refresh the page in your browser.

Testing Keycloak e-mails

The local Keycloak server includes MailDev, a mock SMTP server that you can use to receive and view Keycloak e-mails. It is available on http://localhost:8081.

To set up the local Keycloak server to send e-mails to MailDev:

1. Log in to the local Keycloak server.

2. Go to the “Email” tab in “Realm Settings”

3. Enter the following details:

   • Host: maildev

   • From: keycloak@keycloak

4. Click on “Save”

5. Click on “Admin” in the top-right-hand corner of the page, and click on “Manage Account”

6. Add an e-mail address to the admin account.

   It doesn’t matter what e-mail address you add, as all e-mails will be caught by MailDev. But you do need to add one, otherwise Keycloak will not send e-mails for this account.

The local Keycloak server should now be set up to send e-mails to MailDev. To check that it’s working:

1. Click on the “Back to Security Admin Console” link

2. Click on the “Login” tab in “Realm Settings”

3. Enable “Forgot password”, and click on “Save”

4. Sign out.

5. On the Keycloak log in screen, click on the “Forgot your password?” link

6. Enter your username (admin) in the text field, and submit the form.

7. Visit MailDev. You should see a reset password e-mail from Keycloak.

   

Releasing

The theme can be packaged for release using the following command:

$ npm install
$ npm run build
$ npm run dist

The theme will then be packaged at /govuk.tar.gz.

TODO: deploying to the UK Home Office hosting platform Keycloak Docker container. (i.e. ask for a new Docker Keycloak image to be built and deployed to Kubernetes on https://support.acp.homeoffice.gov.uk/)

keycloak-theme-govuk's Issues

Progressive disclosure arrow missing

The "Sign in directly" progressive disclosure link is now missing its arrow in Firefox.

We should put the arrow back:

Doing so makes it clearer that it isn't a "normal" link and that clicking it won't take the user to a new page.

What's the best way to work on this repository

Hello,

I was wondering what the best way to work on this repository is. Do you have an easy way of testing your changes or did you just manually set up Keycloak locally?

TOTP list missing from TOTP setup page

Using any of the GOV.UK themes, the list of possible TOTP applications is missing from the TOTP setup page.

GOV.UK

Vanilla Keycloak

govuk_elements-ie6 accidentally being compiled for 7 and 8

The following lines in package.json:

    "build:sass:govuk_elements-ie6": "npm-sass sass/govuk_elements-ie6.scss > govuk/login/resources/css/govuk_elements-ie6.css",
    "build:sass:govuk_elements-ie7": "npm-sass sass/govuk_elements-ie6.scss > govuk/login/resources/css/govuk_elements-ie7.css",
    "build:sass:govuk_elements-ie8": "npm-sass sass/govuk_elements-ie6.scss > govuk/login/resources/css/govuk_elements-ie8.css",

should be:

    "build:sass:govuk_elements-ie6": "npm-sass sass/govuk_elements-ie6.scss > govuk/login/resources/css/govuk_elements-ie6.css",
    "build:sass:govuk_elements-ie7": "npm-sass sass/govuk_elements-ie7.scss > govuk/login/resources/css/govuk_elements-ie7.css",
    "build:sass:govuk_elements-ie8": "npm-sass sass/govuk_elements-ie8.scss > govuk/login/resources/css/govuk_elements-ie8.css",

Local Keycloak server no longer runs

Steps to reproduce

As per https://github.com/UKHomeOffice/keycloak-theme-govuk#local-keycloak-server:

1. Make sure you’ve installed and started Docker Community Edition
2. $ npm install
3. $ npm run build
4. $ docker-compose up

Expected behaviour:

The Keycloak server will now be available on http://localhost:8080

Actual behaviour

The Keycloak server is not available, and we get some errors, possibly about not being able to get a database connection. (Console output from docker-compose up attached.)

docker-compose-error.txt

Improve error messages

Nadia Huq has been looking at some of the error messages, and has some improvements.

Screen linked to from credential reset e-mails has no content, and no way to continue

Steps to reproduce

1. Run one of the GOV.UK themes locally

2. Configure it to send e-mails

3. Log into the admin console.

4. Go to the “Users” screen (under “Manage” in the left hand menu)

5. Click on the “View all users” button

6. Click on the ID of the “admin” user

7. Select the “Credentials” tab

8. Under the “Credential Reset” heading, add “Verify Email”, “Update Password” and “Update Profile” in the “Reset Actions” field

9. Click on the “Send email” button

10. Confirm that you want to send e-mail to the user.

11. Sign out of the admin console.

12. In Maildev, select the e-mail that’s just been sent, and click on the link in it.

Expected behaviour

I see a screen with the heading “Perform the following action(s)”, listing “Verify Email”, “Update Password”, and “Update Profile” (as entered in step 8), with a link to proceed.

Actual behaviour

I see a screen with the heading “Perform the following action(s)”, but no actions are listed, and there is no way to continue.

Change the Crown's logo for the SSO login page

I am a developer on the Unadjusted Project, and our RSCAS application uses KeyCloak as the identity provider. We have been asked to update the crown's logo for our application, but we found the SSO login page still shows the queen's crown. 

Although we use our own custom theme (govuk-rscas) for our realm, after digging into the codebase, I understand we can only override some of the wording in the login pages, but it still uses the govuk parent theme. I'd like to know whether we can override the current logo within our theme or if this is something that needs to be done by ACP. 

If it's going to be done by ACP, can you tell me whether this is planned anytime soon?

Text in password field is invisible in some versions of IE 8

Steps to reproduce

In IE 8, visit the login page and type some characters into the password field.

Expected behaviour

The password field has some dots in it, in place of the characters typed in.

Actual behaviour

The password field has no visible characters in it.

Notes

This was reproduced on a POISE desktop (IE 8.0.6001.19727, Product ID: 01405-082-2500885-76264), although it was not reproducible on a POISE laptop (IE 8.0.7601.17514, Product ID: 00392-918-5000002-8507).

Doubts

Hi, I am starting a new project with keycloak, however a situation arose. I created a theme 'manica', and i created another theme 'manica2', and i need to extend everything from 'manica' to 'manica2', but i need to be able to modify the css and im not sure how to do this. I only created a single css file in 'manica' called styles.css, what i need to on theme.properties in 'manica2'?
I was thinking to do something like the image, but it do not work, the newstyle.css is not applied, and cause an error due to de import.