Configuration Tutorial

📘

Repeated Content

This section contains content that can be found described in more detail in the appropriate sections. It is presented here separately to facilitate setting up and configuring App Spaces and Request Origins after the initial installation of the Auth Service.

The following serves as a tutorial to complete the bare minimum configuration to allow an external system ("Request Origin") generate and monitor challenge requests to their users through Privakey CX, but it touches on many important concepts in the Auth Service. For a complete and detailed description of the concepts covered by this tutorial, please see:

• Company Administration
• App Spaces
• Request Origins
• Callbacks
• Communication Service
• Admin Users and Roles

🚧

Example Values

The following tutorial uses example values for inputs, therefore, it is not recommended to follow on a Production instance. The story of the tutorial is configuring our "Financial App" with "The Bank" to be able to push transaction challenges to our users.

To begin, log in as the Company Admin by navigating to /portal on the Auth Service server in a browser. A login prompt will be displayed. Enter the email you used in the Bootstrap Wizard, and the password that was displayed there. Once done, the Company Dashboard will be displayed.

Configuring Communication Service - Self Hosted Only

Note: If you are using Privakey's SaaS offering this section does not apply.

In order for the Auth Service to send notifications to devices, there needs to be a communication endpoint established. To this end, Privakey CX comes with its own communication service which can be used to leverage Firebase notifications. It also supports custom communication services, but this tutorial will assume the use of the default communication service.

Before the default communication service can be used, credentials must be generated by the system, and then the appropriate environment variable set (COMM_SERVER_KEY). To do this, navigate to the Company Dashboard, and select Generate New Credentials.

Copy the new credentials into the COMM_SERVER_KEY environment variable. Note: the server will need to be restarted for the environment variable to be read properly, but this can be done later.

Creating An App Space

The primary organizational unit in the Auth Service is the App Space. This represents a particular user base, and is typically tied to an actual app that is deployed to your users. The system doesn't have any right now, so we'll need to set one up for our fictional financial app. To create one, click "Create New App Space" in the top card.

Enter "Financial App" as the name of the App Space. Here, you can also configure the kind of Identity Provider Type by selecting the drop down. Each type will require a specific set of information which will be displayed in the form. For now, leave the type on Simple and click Save App Space.

After this, you'll be returned to the Company Dashboard. From there, you'll see Financial App in the app space list. Select it to drill down. Here, you'll see the App Space Dashboard. On the top is the App Space overview - there you can edit aspects of the App Space like the name, or the type of IDP. Below that is the Request Origin card, but before we can do anything with that, we need to assign an App Space admin.

At the very bottom is a card for managing admin users who have privileges within this App Space. Since your user only has the Company Admin role associated to it, we lack the permission set required to manage the finer details of the App Space, so we need to attach the App Space Admin role to our user for this App Space. Select View / Manage Admins.

Here, you'll see a list of all the admin users that are associated to this App Space. Since we've just created it, the list is quite empty. Select Create New Admin.

On the next page, is a prompt to enter the email for the new admin user. Here you can enter a brand new email to add a new user to the system, but you can also enter an existing email to attach new roles to that user, which is what we'll do. Enter your user's email address and check App Space Admin, then select Save Admin. The system will attach App Space Admin for this App Space to your user.

Creating a Request Origin

Now that we have the proper role to configure the details of the App Space, it's time to add a Request Origin. A Request Origin represents an external system in place that will communicate with the Auth Service and instruct it to send challenge requests to the users of our app. In our case, we'll want to add The Bank as a request origin, to be able to challenge users of our Financial App. On the App Space Dashboard, select View / Manage All Request Origins.

Unsurprisingly, there are no Request Origins associated with our App Space yet, so select Create New App Space.

On the next page, enter the name of the Request Origin, The Bank. Below the name entry, there are two authentication types: HMAC and Basic. These are the schemes which this Request Origin can authenticate to the Auth Service with. Basic is less technically challenging to implement but is inherently less secure, whereas the HMAC, an authentication value which will need to be constructed by the Request Origin, is more secure. Either one will require recording a passphrase for the new Request Origin, so leave HMAC selected and select Save Request Origin.

After this, you'll be taken to the Request Origin's page. Here, it is important to take note of two things: the GUID, which represents the "user name" of this Request Origin, and the credential value displayed on the page. Be sure to record both values, as they are used during the authentication process for this Request Origin.

❗️

Record the Request Origin Credential

Be sure to securely record the credential displayed here. This is the only time it will be accessible. If you need access to a Request Origin's credential afterward, you'll have to regenerate the credential, which will break the existing Request Origin's access to the Auth Service.

Creating a Callback

Finally, we're ready to create the Callback that The Bank will use to receive updates on challenge requests. The Callback URL can be sent along with the request to challenge a user from the Request Origin. If it is, the specified endpoint will receive updates on the challenge request. Select Create New Callback.

Entering a Callback is simple; type the URL of the location the Request Origin is configured to receive challenge request data from the Auth Service. In our example, www.alerts.thebank.com is the endpoint that will receive any challenge updates.

That's it! The system is now configured to allow The Bank to send challenge requests to users of Financial App, and the Auth Service will push any request updates to the Callback URL at www.alerts.thebank.com.

Each Request Origin can have several Callbacks, each App Space can have several Request Origins, and the Auth Service can support multiple App Spaces. Privakey CX can support transaction intent verification for all of your users across all of your applications.