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
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.
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:
- Log in to the Hanko console, select your organization and select your previously created Hanko Identity project.
- Go to the "Your apps" section in your project settings.
- Click the "Connect app" button in the "Your apps" panel.
- 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
- 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.
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.
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.
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.
Some OAuth 2.0/OpenID Connect Some OAuth 2.0/OpenID Connect client libraries
may be able to auto discover the logout endpoint (also:
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
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
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
You can toggle whether Hanko Identity issues refresh tokens. Enabling this will
configure your client such that refresh tokes are issued when using the