Callsign Auth Module

Using device characteristics, location and user behavior, Callsign can personalize the authentication journey for each user to ensure that the correct authentication level is reached and the user is offered the path of least resistance.

Project Readme

image alt text

AM SERVER MODULE INTEGRATION

Document version: 1.3 (Jan 2018)

©****2018 Callsign Inc., All Rights Reserved

This document is COMMERCIAL IN CONFIDENCE. Neither the whole nor any part of this document may be disclosed to any third party without the prior written consent of Callsign Inc.

The copyright of this document is vested by Callsign Inc. Neither the whole nor any part of this document may be reproduced, stored in any retrieval system or transmitted in any form or by any means without the prior consent from Callsign Inc.

Introduction

Callsign offers features that are additional to the current implementation of identity management functionality offered by ForgeRock. Using device characteristics, location and user behavior, Callsign can personalize the authentication journey for each user to ensure that the correct authentication level is reached and the user is offered the path of least resistance.

Please request this module from Callsign via support@callsign.com

image alt text

Assumptions

  • This guide is for Access Management (AM) version 5.5+, OpenIDM version 3.1+

  • Your Callsign Account Manager has created an organization for you and added you as a Callsign Dashboard ("dashboard") admin. If this is needed please email support@callsign.com to request this.

  • Your user base has been set up on AM

Adding a user

ForgeRock Instructions:

  • Navigate to Realm > Subjects > New…

  • Enter the relevant details for your user

  • Ensure the ID matches the User ID you entered into the Dashboard in step 3 above

  • Click Ok

Further Documentation

Details and guides for other Callsign products can be found at https://developers.callsign.com and https://www.callsign.com/support.

Installation

Existing Auth Chain

The Callsign Server Connector (Server Connector) is a Custom Authentication Module that doesn’t require a UI, and is best used when the OpenAM is protecting APIs. It can be run in two modes:

  • Registration - user is binding their AM account with a Callsign account

  • Authentication - user is performing an authentication on their AM account using their Callsign app as the authentication device.

This guide takes you through both cases.

Module

The Server Connector follows the Custom Authentication Module pattern as described by ForgeRock here.

Copying over the authentication module

  • Copy callsign-openam-server-custom-authentication-module-1.2-distribution.jar into WEB-INF/lib.

  • Ensure that the copied files have the right permissions and are owned by the application container user.

  • Restart your application container.

Registration

Dashboard config

  • Navigate to https://dashboard.callsign.com

  • Type in your Callsign username and authenticate the Callsign Request

  • Click Enterprise on the left hand menu and take a note of the Organization ID

image alt text

  • Click Services on the left hand menu

image alt text

  • Click Add Service

image alt text

  • Click Custom

image alt text

  • Enter a Name e.g. Register

image alt text

  • Setup your integration with the Service Provider Details

  • Enter a Service Name and Description

    • Generate a private key using an HSM and then paste in the public key or;

    • Make a note of the private key ("Service Provider Private Key") as you will need it in the Client UI configuration.

  • Click Next

  • On the Groups screen, if you want all organization users to be able to authenticate, select Active Users. Alternatively, if you want to limit authentication to certain users, select Groups

image alt text

  • Click Next

  • Click Add Transaction Type

  • Click "Link User" from the Type dropdown

  • Select Allow Passcodes if applicable.

  • Select Allow Embedded Callsign ID.

  • Select Callsign as Incoming User ID - this is the ID type you require the user to enter when using the Client UI.

  • Select Org UID as Outgoing User ID - this is the ID type that marries up to a user in the OpenAM database

image alt text

  • Then click Next

image alt text

  • Make a note of the Service ID ("Service ID" in the Client UI Configuration)

  • Then click Complete.

  • Click on Callsign Keys to view the Callsign Public Key.

  • And you are finished with the Dashboard. Next you’ll need to configure the module using the Callsign Public Key, Service ID and Organization ID you gathered from the Dashboard.

Configuring the module

  • Navigate to Realm > Authentication > Modules > Add Module

image alt text

  • Enter CallsignRegister as the Module Name

  • Select Callsign Server as the Type

  • Click Create

image alt text

  • Enter the Authentication Level the user should be given. This indicates the user’s security level

  • Organization ID that we noted down from the Dashboard

  • Service ID that we noted down from the Dashboard

  • Service Provider Private Key that we generated

  • Callsign Public Key that we noted down from the Dashboard

  • Callsign Base URL for production is https://connector.callsign.com/6e

  • Trusted Device ID is a string of your choosing that represents the service you are hosting e.g. the fully qualified domain name is a good option

  • Transaction Type ID that we noted down from the Dashboard

  • Registration must be set to true

  • Click Save Changes

  • Create a chain named CallsignRegistration by clicking Authentication > Chains

image alt text

  • Add DataSource as the first module with Requisite

  • Add CallsignRegister as the second module with Required

image alt text

  • Navigate to /openam/UI/?realm=/&service=CallsignRegistration to test

  • Enter the username and password of a test user

image alt text

  • Enter the Callsign username of a test user

image alt text

  • User ID should be the user’s Incoming User ID (default is their Callsign username).

  • Passcode is for an offline code generated by the user in their app. This is an optional field.

  • Description can be used to display text on the user’s smart device. This is an optional field.

Note: You can also interact with the module via the Authentication API (https://backstage.forgerock.com/docs/openam/12.0.0/dev-guide#rest-api-auth)

Authentication

The Server Connector is a Custom Authentication Module that doesn’t require a UI, best used when you are using OpenAM to protect APIs.

Dashboard config

  • Navigate to https://dashboard.callsign.com

  • Type in your Callsign username and authenticate the login prompt that will appear on your smart device.

  • Click Enterprise on the left hand menu and take a note of the Organization ID

  • Click Services on the left hand menu

image alt text

  • Click Add Service

image alt text

  • Click Custom

image alt text

  • Setup your integration with the Service Provider Details

  • Enter a Service Name and Description

  • Generate a private key using an HSM and then paste in the public key

  • Make a note of the private key ("Service Provider Private Key") as you will need it in the Client UI configuration.

  • Click Next

  • On the Groups screen, select Active Users if you want all organization users to be able to authenticate. Or select Groups, if you want to limit authentication to certain users.

image alt text

  • Click Next

  • Click Add Transaction Type

  • Enter a Name e.g. Login

image alt text

  • Click on the name to show a drop down of the different templated transactions you wish

  • Click "Login" from the Type dropdown

  • Select Allow Passcodes if applicable.

  • Select Allow Embedded Callsign ID.

  • Select Org UID as the Incoming User ID - this is the ID type you require the user to enter when using the Client UI

  • Select Org UID as Outgoing User ID - this is the ID type that marries up to a user in the OpenAM database

  • Then click Next

image alt text

  • Make a note of the Service ID ("Service ID" in the Client UI Configuration).

  • Then click Complete.

  • The final piece of information you will need from the Dashboard is the "Callsign Public Key".

  • Click on Callsign Keys and note this down for the Client UI Configuration.

  • And you are finished with the Dashboard.

Configuring the module

  • Navigate to Realm > Authentication > Modules > Add Module

image alt text

  • Enter CallsignServer as the Module Name

  • Select Callsign Server as the Type

  • Click Create

image alt text

  • Enter the Authentication Level the user should be given. This indicates the user’s security level

  • Organization Id that we noted down from the Dashboard

  • Service Id that we noted down from the Dashboard

  • Service Provider Private Key that we generated

  • Callsign Public Key that we noted down from the Dashboard

  • Callsign Base URL for production is https://connector.callsign.com/6e

  • Trusted Device ID is a string of your choosing that represents the service you are hosting e.g. the fully qualified domain name is a good option

  • Transaction Type ID that we noted down from the Dashboard

  • Registration should be unticked

  • Click Save

  • Navigate to /openam/UI/Login?module=CallsignServer to test

  • Enter the Callsign username of a test user

image alt text

  • User ID should be the user’s Incoming User ID (default is their Callsign)

  • Passcode is for an offline code generated by the user in their app. This is optional

  • Description can be used to display text on the user’s smartphone. This is optional

Note: You can also interact with the module via the Authentication API (https://backstage.forgerock.com/docs/openam/12.0.0/dev-guide#rest-api-auth)

Project Information
Partner
Partner
5.5
2018-02-16
openam
authentication
customAuthModule
frank.gasparovic
here
here