cypress-keycloak

Cypress commands for Keycloak

This package/repository is created based on the fork from https://github.com/babangsund/cypress-keycloak it contains now support for the latest Cypress versions.

Installation

Using npm:

$ npm install cypress-keycloak -D

Using yarn:

$ yarn add cypress-keycloak -D

Then with a module bundler like webpack, add the following line to cypress/support/commands.js | .ts:

// Using ES6
import 'cypress-keycloak';
// using CommonJS
require('cypress-keycloak');

Usage

Two cy commands have been added:

• cy.logout({ ... }):
  • root: string
  • realm: string
  • redirect_uri?: string, for Keycloak >= 18.0.0 use post_logout_redirect_uri instead
  • post_logout_redirect_uri?: string, for Keycloak < 18.0.0 use post_logout_redirect_uri instead
  • id_token_hint?: string
  • path_prefix?: string = "auth"
• cy.login({ ... }):
  • root: string
  • realm: string
  • username: string
  • password: string
  • client_id: string
  • redirect_uri: string
  • path_prefix?: string = "auth"
• cy.loginOTP({ ... }):
  • root: string
  • realm: string
  • username: string
  • password: string
  • client_id: string
  • redirect_uri: string
  • path_prefix?: string = "auth"
  • otp_secret: string
  • otp_credential_id?: string | null = null

Installation:

If you don't want to use login with OTPs you can skip this section.

For generation of OTPs you need to create a new task named generateOTP in your cypress/plugins/index.js | .ts, like discribed in README of Cypress OTP.

To get your OTP secret you need to use e.g. an App for configurating OTP which can display the secret like FreeOTP+. The OTP credential ID can be found in Keycloaks Account Management Console, but only if there are at least two Authenticators configurated. It is only needed for login if you have more than one Authenticator.

Another way is to get these two values is by using the endpoint GET /{realmName}/users/{userId}/credentials.

It is highly recommended to save your username, password, otp_secret and otp_credential_id in .env.*.local or another file within your gitignore.

Example:

describe('thing', () => {
  beforeEach(() => {
    cy.login({
      root: 'https://keycloak.babangsund.com',
      realm: 'stage',
      username: 'babangsund',
      password: 'bacon',
      client_id: 'frontend',
      redirect_uri: 'https://babangsund.com/',
    });

    // or login with OTP
    cy.loginOTP({
      root: 'https://keycloak.babangsund.com',
      realm: 'stage',
      username: 'babangsund',
      password: 'bacon',
      client_id: 'frontend',
      redirect_uri: 'https://babangsund.com/',
      otp_secret: 'OZLDC2HZKM3QUC...', // e.g. 32 chars
      otp_credential_id: '5e231f20-8ca7-35e1-20a694b60181ca9', // e.g. 36 chars
    });
  });

  afterEach(() => {
    cy.logout({
      root: 'https://keycloak.babangsund.com',
      realm: 'stage',
      // using Keycloak < 18.0.0:
      // redirect_uri: 'https://babangsund.com/',
      // using Keycloak >= 18.0.0:
      post_logout_redirect_uri: 'https://babangsund.com/',
    });
  });
});

In case you want to declare these commands only one time with the values it is possible to overwrite them in your cypress/support/commands.js | .ts like this:

Cypress.Commands.overwrite('login', (originalFn) => {
  originalFn({
    root: 'https://keycloak.babangsund.com',
    realm: 'stage',
    username: 'babangsund',
    password: 'bacon',
    client_id: 'frontend',
    redirect_uri: 'https://babangsund.com/',
  })
})

...

And use them like this:

describe('thing', () => {
  beforeEach(() => {
    cy.login();

    // or login with OTP
    cy.loginOTP();
  });

  afterEach(() => {
    cy.logout();
  });
});