Configuring Hanko Identity

This section we will guide you through the process of getting up and running with Hanko Identity.

Set up your Hanko account

If you haven't done so already, first sign up for a Hanko account (it's free). After successful account creation you will be redirected to the Hanko Console. The Hanko Console is where you will manage your organizations, projects and apps.

Create an organization

When you created an account with Hanko, a new organization was created for you - or you could have manually created one. An organization is the starting point for creating projects. An organization can have multiple projects associated with it.

When you create an organization you need to provide a name. The organization that was created for you has a default name. This name can always be changed through the organization dashboard. You can access it through the Manage organization option in the right-hand side dropdown menu in the top navbar.

Create a project

Click the "Create new project" panel. You will be asked to select the type of the project you want to create. Select "Identity" as your project type. You then have the chance to customize the Hanko Identity look and feel to match your brand. You can always revise your choices through the "Brand" settings of your project.

Figure 1: Creating an "Identity" project

Creating a new project results in creation of a Hanko Identity tenant. It may take a short moment for your tenant to be initialized. The project dashboard will provide you with a visual indicator of whether it is ready-to-use.

Connect an application

The next step is to connect your application with the created Hanko Identity tenant. An application can be a native app that executes on a mobile device or a traditional web application that executes on a server.

Communication between your application and Hanko Identity is based on OpenID Connect which is an authentication layer built on top of the OAuth2 Authorization Framework. Connecting an application essentially amounts to registering your application as an OAuth 2.0/OpenID Connect client with Hanko Identity serving as the OpenID Connect provider.

To connect an application:

1. Log in to the Hanko console, select your organization and select your previously created Hanko Identity project.
2. Go to the "Your apps" section in your project settings.
3. Click the "Connect app" button in the "Your apps" panel.
4. In the shown form, provide the following details about your application
   • Application Name: The name of your application
   • Application Type: A traditional web application with a server backend (default) or a native/mobile application. The main difference between these types lies in the application's ability is able to store a static secret in a confidential way. Web apps with a server side backend are able to maintain confidentiality of their credentials, while Mobile apps have no means to keep a static configuration secret confidential.
   • Application URL/Package name: Needs to be all lowercase. This is the URL where your application is running or, in case of a mobile app, your application's package identifier. This value will be the base for redirects in the authentication process.
   • Login Redirect URL: Application URL where Hanko Identity redirects to after successful authentication. This can be for example the same as the application URL or a dedicated route to handle the login, like https://your.app.tld/login or your.bundle.id://login.

Figure 2: Connecting a new application

5. Confirm your choices by clicking "Connect". If you chose "Web app" as your application type you will be shown your client credentials including a client secret. The client secret will be shown only once but new secrets can be generated in your application settings.

Figure 3: Obtaining client credentials

Additional application configuration

After you have connected your app, you will be shown your application settings. Here, you can apply additional configuration to your connected application. This primarily concerns OIDC client settings.

Figure 4: OIDC client settings

Allowed Redirect URLs

Redirect URLs are a crucial part of the underlying OAuth 2.0/OpenID Connect flows at work. They come into play, for example, after a user successfully authenticates with Hanko Identity. Hanko Identity then redirects the user back to your application with either an authorization code or access token in the URL. Because redirect URLs contain sensitive information they must be pre-registered to prevent arbitrary redirects.

Allowed Login Redirect URLs

In addition to the login redirect URL registered during initial app creation, you can register additional URLs that are allowed as redirection targets after authenticating with Hanko Identity.

note

Setting a login redirect URL only registers the URL as an allowed redirect target. When using the Authorization Code flow with Hanko Identity you still need to provide a redirect_uri in the request to the authorization endpoint and it must be a URL that is an allowed login redirect URL. When using an OAuth 2.0/OpenID Connect client library please consult the documentation on how to provide the redirect URL for requests.

Allowed Logout Redirect URLs

Similar to login redirect URLs you can define logout redirect URLs, i.e. allowed URLs in your application that Hanko Identity redirects to after a logout. To log out a user from Hanko Identity, your application must issue a request to the end session endpoint.

note

Some OAuth 2.0/OpenID Connect Some OAuth 2.0/OpenID Connect client libraries may be able to auto discover the logout endpoint (also: end_session_endpoint) through the OpenID Connect Discovery mechanism such that it can be accessed through central library constructs instead of hard-coding it in HTTP requests.

You can always find the most relevant provider metadata returned by the Hanko Identity well-known OpenID Connect configuration endpoint for your Identity project application configuration in the Hanko Console (cf. OIDC server endpoints).

You can specify the URL (post_logout_redirect_uri) to redirect to after a logout in the request to the logout endpoint. If you provide a logout redirect URL in the request to the logout endpoint

• the URL MUST have been pre-registered as an allowed logout redirect URL.
• the request MUST include an id_token_hint, which is a previously issued ID Token that is passed to the logout endpoint as a hint about the end-user’s current authenticated session with the client.

Client secret authentication methods

Your application must define the method that will be used to authenticate to Hanko Identity in order to retrieve OAuth 2.0/OpenID Connect tokens. This can be set using the token endpoint authentication method for your application. If your application/client type is public (i.e. a native/mobile application), client authentication is not required and the value for the setting is set to none. The following methods are supported:

• client_secret_basic: Your application sends its OAuth 2.0 Client credentials using HTTP Basic Authorization.
• client_secret_post: Your application sends its OAuth 2.0 Client credentials in the body of an HTTP POST request as application/x-www-form-urlencoded parameters.

note

Some OAuth 2.0/OpenID Connect client libraries may provide automatic detection of the token endpoint authentication method, e.g. through using the OpenID Connect Discovery mechanism, which may provide data about the supported token endpoint authentication methods in the response to the request to the well-known provider configuration endpoint.

Refresh tokens

You can toggle whether Hanko Identity issues refresh tokens. Enabling this will configure your client such that refresh tokes are issued when using the offline_access scope.