# Signicat developer documentation > Welcome to the Signicat developer documentation, your gateway to unlocking the future of digital identity solutions. This file contains all documentation content in a single document following the llmstxt.org standard. ## Signicat APIs :::info How to connect to Signicat APIs To learn how to set up a connection to any Signicat API and start making requests, see our **Connecting to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). ::: ## Product APIs Our product APIs deliver core functionality for Signicat products. You can explore the API reference documentation for our products using the buttons below: ### Data Verification Verify customer data against different national and commercial data sources. * [**Data Verification API**](/apis/data-verification/): Verify information about natural persons or organisations ### Digital Evidence Management (DEM) Store transactional data or consent messages. * [**Digital Evidence Management API**](/apis/digital-evidence-management/): Securely capture, store and manage audit trail data ### eID and Wallet Hub Manage authentications with eIDs and wallets with the Signicat Authentication REST API. * [**Authentication REST API**](/apis/eid-hub/): Manage end-user authentications using our Authentication REST API ### Electronic Signing Create electronic signatures on contracts, declarations, forms and other documents. * [**Sign API v2**](/apis/electronic-signing/sign-api-v2/): Electronic signatures for both small to medium sized businesses and those within regulated industries * [**Enterprise Sign API**](/apis/electronic-signing/enterprise/): Electronic signatures for businesses within regulated industries * [**Express Signature API**](/apis/electronic-signing/express/): Electronic signatures for small to medium-sized businesses * [**Signicat Archive**](/apis/archive/): Securely store and retrieve signed documents ### ID Document and Biometric Verification Perform electronic identity verification (eIDV) with Assure API. * [**Assure API**](/apis/id-document-and-biometric-verification/): Perform electronic identity verification (eIDV) on end-users using our Assure REST API ### MobileID Implement strong customer authentication on mobile devices. :::note Want to use our next-generation API? The [ReuseID API](/apis/reuseid/) is our next-generation API for ReuseID services, including MobileID. - We recommend this for all customers, so that you can utilise the latest capabilities and improvements. - For existing customers, it is possible to use ReuseID and MobileID in parallel. ::: * [**MobileID API**](/apis/mobileid/): Manage identities and carry out mobile authentication operations * [**MobileID Admin API**](/apis/mobileid-admin/): Manage and administer your MobileID account ### Ongoing Monitoring Monitor changes to the identifying data of natural persons and organisations over time. * [**Person Monitoring API (Deprecated)**](/apis/person-monitoring/): Monitor information on natural persons over time * [**Ongoing Monitoring API**](/apis/ongoing-monitoring/): Monitor information on natural persons and organisations over time ### ReuseID Build your own reusable identities with ReuseID. * [**ReuseID Onboarding API**](/apis/reuseid-onboarding/): Use ready-made flows to onboard ReuseID identities and perform step-up operations * [**ReuseID API**](/apis/reuseid/): Manage identities and carry out ReuseID authentication operations ### Secure Share Create, manage and secure the files you share with others. * [**Secure Share API**](/apis/secure-share/): Share files securely with other people ### Signicat Mint Build custom business workflows and simplify your user journeys with a no-code platform. * [**Signicat Mint API**](/apis/mint/): Manage your flows and analyse your user journey reports ### User management Manage your end-users and create reusable identities globally with Signicat IAM. * [**Signicat IAM SCIM API**](/apis/siam/): Manage identity and access management for your platform ## Management APIs Our management APIs allow you to programmatically manage configurations that are typically handled in the Signicat Dashboard. You can explore the API reference documentation for managing configurations using the buttons below: :::note Note Our management APIs are not fully supported or covered by the same service-level agreements (SLAs) and uptime as our product APIs. This means that although they are maintained and functional, they are intended for developers who are looking to tackle a particular corner case, such as a custom integration. ::: ### Audit logs * [**Signicat Audit API**](/apis/audit-logs/): Query, view and filter activities in the audit logs ### Account management * [**Signicat Account Management API**](/apis/account-management/): Manage your organisations, accounts, and company information. Download invoices ### Domain management * [**Signicat Domain Management API**](/apis/domain-management/): Manage the domains for your account ### Events management * [**Signicat Events Management API**](/apis/events/): Create and manage subscriptions to events published by Signicat services ### OIDC Configuration API * [**OIDC Configuration API**](/apis/oidc-config/): Manage your OIDC client configuration (Advanced) ### Usage analytics * [**Signicat Usage API**](/apis/usage/): View analytics and insights on your API usage to track and optimise performance --- ## Access management We offer Identity and Access Management (IAM) control so that you can manage user profiles and assign them roles. To learn how to do this, see the guides below: * [**Managing roles and permissions**](/docs/dashboard/access-management/managing-roles-and-permissions): Assign roles and administer access to the Signicat Dashboard * [**Managing users**](/docs/dashboard/access-management/managing-users): Manage users for your organisation in the Signicat Dashboard --- ## Managing roles and permissions When inviting new users (for example your team members) to join your organisation, you specify what roles to assign to them based on what tasks they are responsible for. This page is relevant to you if you are an administrator in the Signicat Dashboard. You can administer who has access to your accounts and organisations in the Signicat Dashboard and what permissions they have. :::info Try it in the Signicat Dashboard To manage access rights in the Signicat Dashboard, go to **Signicat Dashboard** > [**Access Management**](https://dashboard.signicat.com/ownidp-management/). ::: ## About roles and permissions Roles are groups of permissions that you can assign to users or API/machine clients (we refer to these entities collectively as _principals_). Permissions allow principals to perform specific actions on Signicat resources, such as the ability to access an API, view invoices or invite other users. To make permissions available to principals, you grant roles to the principals. We divide roles into the following basic types: :::CustomTable{columnWidths="15% 15% 15% 55%"} | Basic role | Request method | Action | Permissions | |:-----------|:---------------|:-------|:------------| | **Viewer** | GET | `read` | Permissions for read-only actions that do not affect state, such as viewing (but not modifying) existing resources or data. | | **Writer** | POST | Action tags | Permissions for write-only actions, but not read or update. An example for this is in Digital Evidence Management (DEM), where a service can create DEM records but not update, delete or read them. | | **Editor** | PUT/CREATE/DELETE | `create` `update` `delete` | All viewer permissions, *plus* permissions for actions that modify state, such as changing existing resources. | | **Admin** | All + Invite users | `*` (all) | All Editor permissions, *plus* permission to invite, remove and grant access to users. | ::: A role contains one or more _permissions_, which offer a granular way of specifying rights. There can be multiple roles with the same permissions. :::note Organisation and Account Admin An `Organisation Admin` has all the permissions for the organisation, and all the accounts belonging to that organisation. An `Account Admin` has all the permissions for a given account but not for the overlying organisation. Some roles apply to a particular product or service, whereas the `Organisation Admin` role has access to all products in the Signicat Dashboard. ::: ## Which roles to assign You control users access to resources with roles. In the following table, you can find some recommendations for common scenarios. :::CustomTable{columnWidths="20% 20% 40% 20%"} | User type | Role | Details | Scope* | |:-----------------|:------------------|:----------------|:------| | Commercial owner | `Organisation Admin` | Access to create/update/delete accounts and configurations. Can invite/edit/delete users on the Organisation and child accounts. Gives billing rights to purchase products on Signicat Marketplace. | Organisation level | | Main technical owner | `Organisation Admin` | Same rights as Commercial owner. | Organisation level | | Financial owner | `Usage Viewer` | Access to view usage and invoices. | Organisation level | | Developer/Technical consultant | `Account Admin` | Access to update account and account configurations. Allowed to invite users and remove users not inherited from parent Organisation. | Account level | | Support roles | `Support Editor` | Access to create, update and view support tickets and comments, including sensitive data. | Organisation level | ::: \* Lowest level where you can grant the role. ## Assign roles You give access to resources by assigning specific roles to users and API/machine clients (collectively referred to as principals). You can also control the scope by deciding whether to assign a role at the organisation or account level. You can assign, edit or remove roles to a principal in the Signicat Dashboard. To grant access to an existing principal, do the following: 1. In the Signicat Dashboard, navigate to **Access Management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions). 2. Hover over the row of a principal and select **Edit**. 3. In the "Edit access" menu, edit the roles of a principal in one of the following ways: - To add a role, select **+ Add** and select a role. - To edit an existing role, select **Change** in the field of a role and select a new role. - To remove a role, select the trash bin icon next to a role. 4. Click **Save** to apply the changes. :::tip Note Users must log in again to view and use a new role. ::: ## Invite members To invite a principal from another organisation or account and grant them access within the scope of your selected organisation or account, do the following: 1. In the Signicat Dashboard, navigate to **Access Management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions). 2. Select **Grant access** in the top right. 3. In the "Grant access" form, configure: :::CustomTable{columnWidths="20% 80%"} | Attribute | Description | |----------------|-------------| | **Scope** | Required. The organisation or account that the role applies to. | | **Principals** | Required. The user, domain or API/machine client for which you want to change access rights. | | **Roles** | Required. Browse available roles in the "Recommended", "By category" or "All available" tabs. Select at least one role. | ::: 4. Click **Save** to apply the changes. :::tip Note Users must log in again to view and use a new role. ::: ## Usage guidelines You can view, search and sort roles in the **Dashboard** > **Access Management** > [**Roles**](https://dashboard.signicat.com/ownidp-management/roles). To view the details and definition of a role, do the following. 1. Go to **Access Management** > [**Roles**](https://dashboard.signicat.com/ownidp-management/roles). 2. Here, select the role name, for example "Account Admin". 3. In the "Account Admin" page, you can view the following fields: - Name: The name of the role - Id: Identifier of the role - Description: Additional information explaining the role function. - Category: The class a role belongs to. - Permissions: A list of all permissions associated with the role. ## Remove access To remove access for a principal: 1. Go to **Access Management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions). 2. Hover over the row of the principal you want to remove access for and click **Edit**. 3. In the "Edit access" overview, click **Remove access**. On the confirmation dialog, approve the changes to remove all the roles assigned to the principal. 4. To only remove access for specific roles, select the bin icon next to a role in the **Roles** section. Then, **Save** at the bottom of the "Edit access" overview. ## Advanced information ### Roles hierarchy Assigning a role to a user for a specific account or organisation impacts the way a user can access resources at the account or organisation level. Imagine you have configured the following in the Dashboard: :::note Example configuration - Organisation 1 - Account A - Account B - Organisation 2 - Account C ::: **Scenario 1** If a user is assigned role X on _Organisation 1_, they will also receive the same role for any sub-level, such as _Account A_ and _Account B_. The user will not receive any role on _Organisation 2_ or _Account C_. **Scenario 2** If a user is assigned role X on _Account A_, they will not receive the same role for _Organisation 1_ and _Account B_. Granting access at the account level limits user access to the resources of the account. ## Tutorial video This video shows you how to invite users, set roles and set permissions in the Signicat Dashboard. --- ## Managing users This page explains how to invite a person to your organisation, configure their access, and remove an existing user. When you invite a new user to join your organisation, you can control user access by [assigning specific roles](/docs/dashboard/access-management/managing-roles-and-permissions.mdx). The permissions you grant to users in your organisation determine the features they can use through Signicat products and services. :::info Try it in the Signicat Dashboard To manage the users in your Signicat organisation, go to **Signicat Dashboard** > **Access Management** > [**Users**](https://dashboard.signicat.com/ownidp-management/users). ::: ## Inviting users As an `Organisation Admin` or `Partner Organisation Admin`, you can manage users within your organisation(s). You can invite a person to join your organisation using the Signicat Dashboard. :::warning Note Machine clients and applications are excluded from the flow to invite a user. See our page on [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx) to find out how to grant access to machine clients and applications. ::: ### Prerequisites - You must have the `Organisation Admin` or `Partner Organisation Admin` role to invite users to an organisation. - `Account Admin` roles are only allowed to invite and remove users at the account level, that are not inherited from a parent organisation. ### Invite a new user To invite a new user to your organisation: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com). 2. Go to **Access Management** > [**Users**](https://dashboard.signicat.com/ownidp-management/users) and select **Invite users**. Alternatively, you can select **Invite peers to Organisation** in the Dashboard homepage. Invite users screen 3. In the invitation form, fill in: :::CustomTable{columnWidths="20% 80%"} | Attribute | Description | |--------------------|-------------| | **Email** | Required. The email address where to send the invitation. If the user already exists, they receive an email with a prompt to accept access to the new role(s) you assigned them. | | **First name** | Optional. The first name of the user. Specify a value to prefill the user registration form. The user can override this value during registration. | | **Last name** | Optional. The last name of the user. Specify a value to prefill the user registration form. The user can override this value during registration. | | **Organisation** | Required. The name of the organisation for which you want to give access. | | **Account** | Optional. Add the name of an account only if you want to limit access to a specific account. Leave the field empty to grant access to all accounts under the organisation. | | **Roles** | Required. To add a role select the **+ Add** button and pick the role(s) you want to grant to the user. Browse the "Recommended", "By category" or "All available" tabs to find a role. You can learn more about roles in the [Which roles to assign](/docs/dashboard/access-management/managing-roles-and-permissions.mdx#which-roles-to-assign) section on our page on [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx). | ::: 4. Click **Send invite** to invite the user. The person you invited will receive an email with instructions to sign up and accept the invite. Invitations expire after three days. ### Examples :::details User invitation settings for Marketplace To purchase products on Signicat Marketplace, you need billing access. To invite a user that can buy products, specify the following settings: - **Account**: Leave empty - **Roles**: `Organisation Admin` ::: ## Removing users To permanently delete the profile of a user in your organisation, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. As an alternative, you can remove all access for a user. To do this: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com). 2. Browse to **Access Management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions). 3. Hover over the row of the user you want to remove access for and click **Edit**. 4. In the "Edit access" overview, click **Remove access**. On the confirmation dialog, approve the changes to remove all the roles assigned to the user. Now, the user cannot view or access any of the services in your organisation, including viewing the name of your organisation and accounts. Changes apply immediately. Learn more about roles and permissions on our page on [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx). ## Tutorial video This video shows you how to invite users, set roles and set permissions in the Signicat Dashboard. --- ## Billing and analytics We offer billing and analytics tools so that you can manage your invoices and transactions. To learn how to do this, see the guides below: * [**Invoices**](/docs/dashboard/billing-and-analytics/invoices): Learn how to use the Signicat Invoices service * [**Transactions**](/docs/dashboard/billing-and-analytics/transactions): Learn how to use the Signicat Transactions service --- ## Invoices The Signicat **Invoices** service provides you with information about all invoices and their details for a selected organisation, if the information is available. The list also indicates if a correction has been sent to you. This is shown on the list item containing the invoice. :::info Try it in the Signicat Dashboard To manage invoices in the Signicat Dashboard, go to **Signicat Dashboard** > **Billing and Analytics** > [**Invoices**](https://dashboard.signicat.com/invoices). ::: ## How does the Invoices service work? ### Get started You can view invoices for your organisation in the Signicat Dashboard. To do this: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com). 2. Navigate to the [**Invoices**](https://dashboard.signicat.com/invoices) service. :::tip Where can I find the Invoices service? From the Signicat Dashboard, you can access the Invoices service in two ways: - Under the **Management** heading, click **Invoices**. - In the left-side menu, expand the **Billing & Analytics** dropdown menu, then click **Invoices**. ::: ### Available information The information that is available to you in the Signicat Dashboard depends on how your organisation is set up. Either: - The organisation is the receiver of its invoices. - The organisation is configured with a parent organisation. In this case, the parent organisation is the receiver of the invoices. :::tip Want to learn more? You can read more about how organisations and accounts work on the [Organisation management](/docs/dashboard/organisation-management/) documentation. ::: #### Organisation :::note What does this apply to? The following applies to organisations where: - The organisation is set as the billing account. - The organisation receives their own invoices. ::: All invoices for the organisation are listed on the invoices overview page. For the period of time up until when an invoice is generated and sent to you, you can see a draft of the invoice with the listed transactions. During this period, the list item will be marked with the status **Draft**. #### Account :::note What does this apply to? The following applies to accounts where: - Its organisation is set as the billing account. ::: All invoices for the account's organisation are listed on the invoices overview page. All accounts under the organisation will show the same invoices in this section, as invoices are linked to the organisation. For the period of time up until when an invoice is generated and sent to you, you can see a draft of the invoice with the listed transactions. During this period, the list item will be marked with the status **Draft**. #### Parent organisation :::note What does this apply to? The following applies to organisations where: - The parent organisation is set as the billing account. ::: All invoices for the parent organisation in addition to all invoices for its child organisations are listed on the invoices overview page. For the period of time up until when an invoice is generated and sent to you, you can see a draft of the child accounts' invoices with the listed transactions. During this period, the list item will be marked with the status **Draft**. #### Child organisation :::note What does this apply to? The following applies to organisations where: - Its parent organisation is set as the billing account. ::: No invoices or invoice drafts will be shown on the invoices overview page. ### Sorting invoices By default, invoices are listed in reverse chronological order. This means that the invoice generated most recently is at the top of the list. You can sort the list of invoices using the following parameters: - Date - Reference - Amount - Status To do this: 1. Navigate to the column heading that you want to sort the invoices with. 2. Click the arrows icon beside the heading to sort in ascending or descending order. ### Filtering invoices You can filter invoices by date and status. to do this: 1. On the invoices overview page, click the **Filter** button. 2. Use the tick boxes to apply **Date** and **Status** filters: - If you select **Date**, then you are prompted to set a desired time period. - If you select **Status**, then you are prompted to set desired statuses. 3. Click **Apply** to confirm your choices. ## What does an invoice look like? Each line has the information below: :::CustomTable{columnWidths="25% 75%"} | **Data field** | **Description** | | :--- | :--- | | Date | The date when the invoice is sent. | | Reference | The reference of the invoice. | | Amount | The total amount of the invoice. **Note**: Any corrections will also be displayed here. | | Status | Indicates whether the invoice has been invoiced, or if it only has a _Draft_ status. | ::: ### Invoice statuses To learn about what the different invoice statuses mean, see the table below: :::CustomTable{columnWidths="25% 75%"} | **Status** | **Description** | | :--- | :--- | | Invoiced | The billing account has received its invoice. | | Draft | The billing account can see a draft which includes the usage so far for that period. With this status, the invoice is not generated or sent. | ::: ### Invoice details To see the details for a particular invoice, you must select it from the list of invoices. Once you have done this, you can view the following fields: :::CustomTable{columnWidths="25% 75%"} | **Data field** | **Description** | | :--- | :--- | | Product name | The name of the product being used from Signicat. **Example**: Norwegian BankID High - Authentications | | Period | The time period of usage for which you are being invoiced. | | Quantity | The number of transactions in the given time period. | | Unit price | The price per transaction. | | Total amount | The total price for all usage. | | Usage data | An expandable field which shows a breakdown of information for the method. **Note**: If you are not migrated to our new platform, then the breakdown will differ with a separate *Usage* section. | ::: #### Usage data Once you have expanded the usage data field, you can view the following fields which provide a breakdown of information for the method: :::CustomTable{columnWidths="25% 75%"} | **Usage data field** | **Description** | | :--- | :--- | | Endpoint name | The name of the endpoint used for the transaction. | | Method name | The name of the method used. **Example**: nbid | | Profile | The name of the theme used. **Note**: This field can be empty. | | Count type | The type of transaction that is counted. This is given as one of the following states: *Started*, *Completed* or *Loaded*. **Note**: *Cancelled* is not classified as unique state; it is counted as the *Started* state. For more information about the different states, see our [Transactions](/docs/dashboard/billing-and-analytics/transactions.mdx#what-does-a-transaction-look-like) documentation. | | Quantity | The total number of transactions for the product. | ::: ### Export invoice To export an invoice, you need to do the following: 1. From the list of invoices, select the invoice that you want to export. 2. From the invoice details page, click the **Export invoice** button. 3. From the dropdown menu, select whether you want to export the invoice as a **PDF** or an **Excel** file. ## Support If you have any questions about your invoices or require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Transactions The Signicat **Transactions** service provides you with information about all transactions for a selected account. :::info Try it in the Signicat Dashboard To manage transactions in the Signicat Dashboard, go to **Signicat Dashboard** > **Billing and Analytics** > [**Transactions**](https://dashboard.signicat.com/transactions). ::: :::note Informational use only The overview of transactions shown in the Transactions service is for informational use only. This means that there may be slight differences when compared to the invoiced amount of transactions, as can be seen in the **Invoices** service. ::: ## How does the transactions service work? ### Get started You can view transactions for your account in the Signicat Dashboard. To do this: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com). 2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to view transactions for. 3. Navigate to the [**Transactions**](https://dashboard.signicat.com/transactions) service. :::tip Where can I find the Transactions service? From the Signicat Dashboard, you can access the Transactions service in two ways: - Under the **Management** heading, click **Transactions**. - In the left-side menu, expand the **Billing & Analytics** dropdown menu, then click **Transactions**. ::: ### Changing accounts Only transactions for the account you currently have selected in the Signicat Dashboard are shown. To view transactions for another account, you need to: 1. Navigate to the top navigation bar in the Signicat Dashboard. 2. Expand the dropdown menu next to your organisation name. 3. Select the account that you want to view transactions for. ### Setting the time period The Transactions service shows an overview of transaction data for the selected time period. - The content in the transactions overview is updated daily. - Transactions will be available in the transactions overview the day after they occur. To specify the time period that you want to view transactions for: 1. Click the **Select a period to view transaction** field. 2. Use the calendar interface to select a start and finish date for the time period. :::tip Tip You can also use the options shown under the **Quick select** section to set the time period with a configured amount, such as the last three months. ::: 3. To confirm your selection, click the **Select** button. ### Grouping transactions You can group the list of transactions using one of the available groupings, which are displayed as tabs above the table of transactions: - Daily - Monthly - Quarterly - Yearly ## What does a transaction look like? Each transaction is listed with the following data fields: :::CustomTable{columnWidths="25% 75%"} | **Data field** | **Description** | | :--- | :--- | | Date | The date of the transaction. | | Usage type | Information about what product is being used for the transaction. **Example (migrated)**: `srn:sue:1:authbroker:nbid:auth` **Example (not-migrated)**: `com.signicat.services.nbidjs.authentication.method` | Method name | The name of the method used. This field is only shown if not included in the _Usage type_. **Example**: nbid | Product | The name of the product being used from Signicat. **Example**: Norwegian BankID High - Authentications | | Invoiced | **CPQ**: The total number of transactions with status _Invoiced_. **Legacy**: This is always `0`. You need to check the invoice for information. | | Completed | The total number of transactions with status _Completed_. | | Started | The total number of transactions with status _Started_. | | Loaded | The total number transactions with status _Loaded_. | | Failed | The total number of transactions with status _Failed_. | ::: ### Transaction states To learn about what the different transaction states mean, see the table below: :::CustomTable{columnWidths="25% 75%"} | **State** | **Description** | | :--- | :--- | | Invoiced | The transactions have been invoiced. | | Started | The transaction started, but did not finish with a successful response such as _Completed_. **Note**: Cancelled transactions are included in the _Started_ state, as it is not a successful response. | | Completed | The transaction completed successfully. **Note**: When a transaction is completed, the status changes from _Started_ to _Completed_. | | Loaded | The transaction initialised, but never progressed from its initial state. **Note**: This state only applies if you have not migrated to our new platform. | | Failed | The transaction ended in an error state, due to an error occurring on our side. | ::: ## Support If you have any questions about your invoices or require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Communication The Signicat **Communication** service lets you manage your configurations for SMS messages and email. These custom settings override the default Signicat settings. :::info Try it in the Signicat Dashboard To access the communication service, go to **Signicat Dashboard** > **Branding** > [**Communication**](https://dashboard.signicat.com/communication). ::: ## What is communication? We use SMS messages and emails to communicate important information from Signicat services to your end-users. For example, when you want a document to be signed, an email or SMS message can be sent to your end-user with a signing link. With this service, you can: - Customise the email and SMS sender name. - Specify the preferred primary and secondary SMS provider. - Add your own custom domain for sending emails. - Customise your own email sender address prefix. - Directly connect to your own SMTP server for emails. - Look at delivery logs and the corresponding status. ### Example use case When you want a document to be signed, the account's email configuration is retrieved, and if not overridden, a Signicat default email is used. You may override these settings to customise the email domain, sender and sender address being sent from provided services such as Signature. ## What does a test message look like? If you are testing our services with a sandbox account, then we prepend all emails and SMS messages with a test message warning. - For emails, we prepend the contents with a warning banner. This banner describes that the email is intended solely for testing purposes and warns the recipient against clicking on any of the links, unless they are actively conducting tests. - For SMS messages, we prepend the message with `TEST SMS:`. :::info Why do we do this? We do this to protect recipients from clicking on potentially malicious links that appear to come from Signicat. ::: ## SMS From the [**SMS**](https://dashboard.signicat.com/communication/sms) page, you can manage the SMS settings for your account. ### Customise the SMS sender name This is the name of the sender that is displayed to the recipient of the SMS when receiving the text. To change this: 1. From the [**SMS**](https://dashboard.signicat.com/communication/sms) page, click the **Edit** button. 2. In the **Sender** field, replace 'Signicat' with the name of your choice. The name must consist of 3 to 11 alphanumeric characters (`A-Za-z0-9`). It can also contain dots (.) and spaces. 3. Click the **Save** button. ### Customise the primary SMS provider This is the primary SMS provider to use when sending SMS messages. To change this: 1. From the [**SMS**](https://dashboard.signicat.com/communication/sms) page, click the **Edit** button, then click the **Primary SMS provider** field. 2. From the dropdown menu, select the provider of your choice. 3. Click the **Save** button. ### Add a secondary SMS provider This is the secondary SMS provider to use as a fallback if there is a temporary failure with the primary SMS provider. This is disabled by default. The primary SMS provider is always used first. If there is a failure, then the SMS message is automatically attempted with the secondary provider if enabled. To add a secondary SMS provider: 1. From the [**SMS**](https://dashboard.signicat.com/communication/sms) page, click the **Edit** button, then click the **Secondary SMS provider** field. 2. From the dropdown menu, select the provider of your choice. 3. Click the **Save** button. ## Email From the [**Email**](https://dashboard.signicat.com/communication/email) page, you can: - Manage the email settings for your account. - Add your own custom email domain for use in sending emails. ### Customise the from address prefix The full email address uses the form `{from_address_prefix}@{domain_name}`. The Signicat domain is the default setting, hence the default email address is `noreply@email.signicat.com`. To customise the `from_address_prefix`: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **Email settings** tab, click the **Edit** button. 2. In the **From address prefix** field, replace 'noreply' with the prefix of your choice. 3. Click the **Save** button. ### Customise the email sender name To customise the name of the sender that is displayed to the recipient when they are viewing the email: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **Email settings** tab, click the **Edit** button. 2. In the **Sender** field, replace 'Signicat' with the name of your choice. 3. Click the **Save** button. ### Use custom SMTP server settings To specify whether to connect to a custom SMTP server, and use a sending API key: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **Email settings** tab, click the **Edit** button. 2. Click the toggle button beside **Use custom SMTP server settings**. A new set of fields will appear. 3. Complete the fields as required. :::details What do the fields mean? | **Field name** | **Description** | | :-- | :-- | | Port | Set which SMTP port to use when connecting to the SMTP server. The default is **25**, and available options are **25**, **587** and **465**. | | Host Address | **Required**: Set which SMTP host to connect to. For example: `smtp.mydomain.com`. | | Sender Address | **Required**: Set the default sender address to use when sending emails. For example: `noreply@email.mydomain.com`. If the **Sender address cannot be overridden** box is ticked, then the **Sender Address** cannot be overridden via any API calls, and is always used. | | Authentication flow | Set the method to authenticate to the SMTP server. This can be either: **None**: Requires no authentication. **Username and password**: Requires a valid username and password for the SMTP server. **XOauth2**: Requires a client ID, client secret, necessary scopes and endpoint for retrieving an access token on your behalf. | | Disable Certificate Validation | Set whether certificates from the SMTP server being connected to are required to be signed by globally trusted certificate authorities. Certificate validation is disabled by default. | ::: 4. Click the **Save** button. ### Add your own custom domain You can add your own custom domain for use in sending emails. :::tip Tip If you set up your own domain, then you are using SMTP settings. ::: To do this: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **My domains** tab, update the **Domain** field with your desired domain. For example: `my.domain.com`. 2. Optionally, you can define a custom DKIM selector instead of using a generated one. All characters must be lowercase, with an allowed length of between 2 and 11 characters. 3. Click the **Add domain** button. 4. Your DNS records are generated and are visible on the next page. You can now add these to your own hosting provider. 5. After adding these DNS records to your hosting provider, periodic checks occur which check if the domain has been verified and is ready for use. You can also click the **Verify DNS** button to manually attempt to verify the domain. 6. When verified, the **Use Domain** button is no longer greyed out and can now be clicked. 7. Once clicked, a pop-up appears where you can add the desired prefix for the default sender address, for example: `mycompany`. The domain is appended, separated by `@`; this results in a default sender address of `mycompany@my.domain.com`. 8. Click the **Confirm** button. Your custom domain is now active for future emails. ### Edit one of your domains 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **My domains** tab, click the three dots under the **Actions** header 2. Click **Edit** from the dropdown menu. 3. You are taken to the individual domain view where the DNS records are, where you can make any desired changes. ### Delete one of your domains :::note Note You can only delete a domain if it is not currently in use. ::: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **My domains** tab, click the three dots under the **Actions** header. 2. Click **Delete** from the dropdown menu. 3. As a preventative measure against accidental deletion, you must type the domain which you want to delete in the provided field in the dialogue box. 4. Press the **Delete domain** button in the dialogue box. ### Use one of your domains :::note Note You can only use a domain if it is not already in use and it is verified. If not, then the **Use domain** option is not visible in the dropdown menu. ::: 1. From the [**Email**](https://dashboard.signicat.com/communication/email) page, on the **My domains** tab, click the three dots under the **Actions** header. 2. Click **Use domain** from the dropdown menu. ## Logs From the [**Logs**](https://dashboard.signicat.com/communication/logs) page, you can view logs of your recently sent email and SMS message events using either the **SMS** or **Email** tab. When you have sent an email or SMS for that specific account, these messages appear with their status on this page. ### Filter by event status To filter the events by the event status: 1. From the [**Logs**](https://dashboard.signicat.com/communication/logs) page, select either the **SMS** or **Email** tab. 2. Expand the first dropdown menu and make a selection. :::details What are the possible statuses? - For SMS, the possible statuses are: - All - Delivered - Sent - Failed - For email, the possible statuses are: - All - Delivered - Opened - Sent - Failed ::: ### Order by timestamp To order the events by their timestamp: 1. From the [**Logs**](https://dashboard.signicat.com/communication/logs) page, select either the **SMS** or **Email** tab. 2. Click the **Timestamp** button to sort via ascending or descending order. ### View the raw JSON or message for an event To open up the individual event to view the raw JSON and message itself: 1. From the [**Logs**](https://dashboard.signicat.com/communication/logs) page, view either the **SMS** or **Email** tab. 2. Click the three dots under the **Actions** header, to the right of the event you want to see further details for. - To view the raw JSON, click **View JSON** from the dropdown menu. - To view the message, click **View message** from the dropdown menu. --- ## Branding We offer branding tools for customising communication settings and themes, so that you can create a consistent experience for your end-users. To learn how to do this, see the guides below: * [**Communication**](/docs/dashboard/branding/communication): Configure the Signicat Communication services * [**Theming**](/docs/dashboard/branding/theming): Customise themes for branded experiences --- ## Theming The Signicat Theming services lets you customise your themes to offer a consistent branding experience to your end-users. :::info Try it in the Signicat Dashboard To manage your themes in the Signicat Dashboard, go to **Signicat Dashboard** > **Branding** > [**Theming**](https://dashboard.signicat.com/themes-mgmt). ::: :::note Which products support theming? We are in the process of rolling out theming to all Signicat products. For details, see [Which products support theming?](#which-products-support-theming). ::: ## About theming The Signicat Theming service allows you to configure the appearance of the content that is presented to your end-users, so that you can provide a cohesive user experience and conform with your company's branding guidelines. With our Theming service, you can determine: - The placement of a custom logo. - The placement and size of the headers. - The background colour or image. - The alignment of the widget. - The alignment of the content. - The colour palette used for the background, headers and buttons. - The border curvature. - The typography. :::info Are themes the same as graphical profiles? With the new Theming service, you can do everything and more that you could do previously with the [Graphical profiles](https://developer.signicat.com/cs/enterprise/docs/customisation/#graphical-profile) editor. ::: ### Which products support theming? - eID and Wallet Hub :::note Graphical profiles for MitID It is not possible to use Theming service with MitID. If you want to customise the graphical profile for MitID, you can use the [Advanced graphical profile (add-on)](/identity-methods/mitid/user-interface/ui-guidelines.mdx#advanced-graphical-profile-add-on) instead. ::: :::note Typography Swedish BankID and FTN do not yet support typography. ::: - ID Document and Biometric Verification - Signicat Mint - MobileID - Electronic Signature API :::note Note - If you are using the Enterprise Electronic Signature API, then we rely on our [Graphical profiles](https://developer.signicat.com/cs/enterprise/docs/customisation/#graphical-profile) editor. To order or modify a graphical profile for the Electronic Signature API, you can contact your key account manager. - If you are using the Express Electronic Signature API, then refer to the [Theming](https://developer.signicat.com/cs/express/docs/signature/web-ui-config.html#theming) guide in the Express Signature documentation. - If you are using MitID Express or Enterprise, then refer to the [Advanced graphical profile (add-on)](/identity-methods/mitid/user-interface/ui-guidelines.mdx#advanced-graphical-profile-add-on) guide. ::: ### Built-in accessibility End-user applications that you build using our Theming service have built-in accessibility that meets WCAG standards, as we embed accessibility best practices such as ARIA roles and keyboard navigation directly within each component. This ensures an accessible and consistent user experience across all environments where these components are used. ## How does theming work? You can create custom themes with the [Theming](https://dashboard.signicat.com/themes-mgmt) service in the Signicat Dashboard, which can be configured to your requirements. :::note Note Themes do not affect the appearance of the Signicat Dashboard, **only** the appearance of the content that is presented to your end-users. ::: - A theme can be created on an account level, and can be applied on an account or domain level. - You can only apply one theme at an account level. This becomes the default theme for the children of that level. :::tip What does this mean? This means that if you set the theme at an account level, then any domain under this account gets the theme automatically applied. ::: - You can apply one or more themes at a domain level. ### What access rights do I need? In order to work with the Theming service, you need to ensure that you also have a role which provides you with the minimum level of access on an account level, such as the **Account Management Account Viewer** role. This is because themes are applied at an account and/or domain level. This applies to the theme-related roles listed below, which have to be applied at an account level: - Theme Editor - Theme Admin - Theme Viewer :::tip What does this mean? For example, in order to use the **Theme Editor** role to create and update a theme, you also need at least a basic read-only account-level role, such as **Account Management Account Viewer**. Without a role that gives you the minimum amount of access, you are not able to create and update the theme. ::: ### Get started with the Theming service You can create and manage themes in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Branding** > [**Theming**](https://dashboard.signicat.com/themes-mgmt). 2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to make changes to. :::note Success! You are now in the account theming section, where you can see the default theme setting. From here, you can customise the theme for the selected account. ::: ## How to create a new theme To create a new theme: 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, click the **+ Add new** button. 2. Populate the fields in the dialog box, then click the **Create** button. :::note Success! You have now created a new theme. This theme is now selectable from the **Selected theme** dropdown menu. ::: ## How to customise a theme Once you have created a theme, you can customise it to your requirements. :::warning Important You must ensure that you are compliant with [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)(WCAG) regarding contrast between typography colours and other elements. ::: 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, use the **Selected theme** dropdown menu to select the theme that you want to edit. 2. Click the **Edit theme** button. 3. Make your desired changes to the theme using the editor. You can customise the: - Header - Widget - Typography - Colours - Borders - Background :::note Maximum file size If used, the maximum logo and background image size is 5MB. ::: 3. Once you have finished editing your theme, click the **Save changes** button. ## How to apply a theme ### Apply a theme on an account level 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, you can see the name of the account you are currently making changes to in the **Accounts and domains** dropdown menu. 1. Click the **Use different themes for domains** toggle button. 2. Select the domain you want to make changes to from the **Accounts and domains** dropdown menu. 3. Use the **Selected theme** dropdown menu to select the theme that you want to apply to the account or domain. 4. Click the **Apply theme** button. ### Apply a theme on a domain level If you have created domains under your account, then it is possible to apply a different theme to each domain that you have. If you want to do this, you must use the following order: 1. Set the custom theme for the account. 2. Set the custom theme for the domain(s). If you set the account theme after the domain themes instead, then the account theme will overwrite the saved custom domain themes and your work will be lost. We recommend that you create two distinct themes first. By doing this, you prevent any loss of work if you decide that you want to apply one theme at an account level and one theme for a specific domain. To set a custom theme for a domain: 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, click the **Use different themes for domains** toggle button. 2. Select the domain you want to make changes to from the **Accounts and domains** dropdown menu. 3. Use the **Selected theme** dropdown menu to select the theme that you want to apply to the account or domain. 4. Click the **Apply theme** button. #### Apply multiple themes for a domain If you have created domains under your account, then it is possible to apply multiple themes to each domain that you have. To do this: 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, click the **Use different themes for domains** toggle button. 2. Select the domain you want to make changes to from the **Accounts and domains** dropdown menu. 3. Click the **Use multiple themes for this domain** toggle button. 4. Select the theme that you want, then click the **+ Add theme** button. Repeat this step for every theme that you want to apply. The added themes will appear in the list below. 5. Once you are happy with your selection, click the **Apply multiple themes** button to proceed. ## How to export a theme You can use the export feature to reuse themes for either the same account or another account. Given that you have the correct permissions in the destination organisation and account, it is possible to export themes to another account in the same or another organisation. - A theme can be exported multiple times. - Every exported theme is unique with its own theme ID. - Every exported theme can be edited independently under the destination account. :::note Required permissions To export a theme, you need to have both: - The minimum level of access on an account level, such as the **Account Management Account Viewer** role. - The permissions associated with the **Theme Editor** in the destination organisation. ::: To export a theme: 1. In the [Theming](https://dashboard.signicat.com/themes-mgmt) service, ensure that the correct account is selected. If not, you can update this using the dropdown menu in the top navigation bar. 2. Use the **Selected theme** dropdown menu to select the theme that you want to export, then click the **Export theme** button. 3. Use the **Select organisation** dropdown menu to select the target organisation for the exported theme. 4. Use the checkboxes under **Your selected accounts** to select one or multiple account that you want to export the theme to. 5. Click the **Export theme** button. ## Specify a theme per request If you have multiple themes for a domain or account, then you can specify which theme you want to use per request. The way you do this depends on which [authentication protocol](/docs/eid-hub/) you use. ### OpenID Connect To specify a theme when using OpenID Connect, you must use the `acr_values` URL parameter. ```url title="Example: Specify a theme with OIDC" acr_values=theme:xfwfyv1340 ``` In this example,`xfwfyv1340` is the theme ID. You can find and copy the required theme ID from the Themes service in the Signicat Dashboard. :::tip Want to learn more? To learn more about ACR values, see [acr_values](/docs/eid-hub/oidc/oidc-implementation.mdx#acr_values) in our the OIDC documentation. ::: ### Authentication REST API To specify a theme when using the Authentication REST API, you must use the optional `themeId` field when creating authentication sessions. ```json title="Example: Specify a theme with the Authentication REST API" "themeId": "agkaa12" ``` In this example,`agkaa12` is the theme ID. You can find and copy the required theme ID from the Themes service in the Signicat Dashboard. :::tip Want to learn more? To learn more about this, see our [Authentication REST API reference documentation](/apis/eid-hub/). ::: ### SAML 2.0 Information will follow soon. --- ## Access tokens An access token is a string that encodes the security information used to authenticate and provide authorisation information to Signicat APIs. Your application sends the access token when making calls to Signicat APIs. ## Token caching We recommend that you cache access tokens when interacting with Signicat APIs. This helps to limit your network usage and resource overhead, whilst reducing traffic to Signicat servers. For example, you can cache your access tokens using a memory cache, such as Redis or a simple in-memory cache. You then renew the tokens when they get close to the token expiration time. If the access tokens fail, then you can configure your application to retry the request one more time. ## Token lifetime An access token has a relatively short lifetime. This is set to 600 seconds by default. Once the access token expires, it can no longer be used. This is very important for security. To obtain a new access token, you need to send a new access token request. You can edit the default token lifetime of your API client. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**API clients**](https://dashboard.signicat.com/api-clients/). 2. On your API client, click **Edit**. 3. On the **Overview** tab, set the desired value in the **Access token lifetime** field. :::note Allowed values You can set a value from 1 to 3600 seconds. ::: 4. Select **Update** to save the changes. --- ## HTTP request requirements Incoming HTTP requests to any of our APIs must meet specific requirements. If a request does not follow the required structure, then it will fail and return an appropriate error response. ## POST and PUT requests For HTTP/1.1 `POST` and `PUT` requests, our APIs always expect a body. This means the request must explicitly indicate the body's length or use chunked transfer encoding, even if the body is empty. To satisfy this requirement, the request must include either: - A `Content-Length` header. - A `Transfer-Encoding` header with chunked as the final value. If neither of the above options are present, or if chunked is not the final encoding listed, then the request will fail and return an error message with a `411 Length Required` status code. :::note Note This requirement only applies to HTTP/1.1. It does not apply to HTTP/2, which handles message framing differently. ::: ```http title="Example: HTTP/1.1 POST request with Content-Length header" POST /example-api HTTP/1.1 Host: api.signicat.com Content-Type: application/json Content-Length: 16 {"name": "Jane"} ``` ```http title="Example: HTTP/1.1 POST request with Transfer-Encoding header" POST /example-api HTTP/1.1 Host: api.signicat.com Content-Type: application/json Transfer-Encoding: chunked 10 {"name": "Jane"} 0 ``` :::note Case: Empty body Request with empty body must also include `Content-Length: 0` or `Transfer-Encoding: chunked`. ::: ## GET requests For HTTP/1.1 and HTTP/2 `GET` requests, our APIs do not support a body. Any `GET` request that includes a body will fail and return an error message with a `400 Bad Request` status code. --- ## Advanced settings This page contains topics for further configuring your connection to Signicat APIs. You can use the buttons below to learn about advanced settings such as configuring the access token lifetime and the requirements when making a HTTP request to Signicat APIs: * [**Access tokens**](/docs/dashboard/connect-to-signicat-apis/advanced-settings/access-tokens): Learn about configuring access tokens * [**HTTP request requirements**](/docs/dashboard/connect-to-signicat-apis/advanced-settings/http-request-requirements): Learn about HTTP request requirements --- ## Connect to Signicat APIs All Signicat APIs are hosted at the `api.signicat.com` domain and use the OAuth 2.0 protocol for authorisation. Each request must include an `Authorization` header to authenticate and authorise operations. ## Set up a connection Learn how to connect to any Signicat API by creating an API client, obtaining an access token and making your first request. * [**Quick start guide**](/docs/dashboard/connect-to-signicat-apis/quick-start-guide): Learn how to set up a connection to any Signicat API * [**All Signicat APIs**](/docs/dashboard/connect-to-signicat-apis/signicat-apis): Explore an overview of all Signicat API references ## Advanced connection settings Learn how to manage advanced settings when connecting to Signicat APIs, such as token lifetime and HTTP request requirements. * [**Advanced settings**](/docs/dashboard/connect-to-signicat-apis/advanced-settings/): Learn how to manage advanced settings --- ## Quick start guide # Quick start guide Learn how to set up a connection to any Signicat API. This quick start guide shows you how to: 1. Complete the initial preparations, if required. 2. Create an API client in the Signicat Dashboard. 3. Set permissions for your API client. 4. Request an access token using your API client credentials. 5. Use the access token to make an API request. Make your first request to an API. :::details Authorisation flow sequence diagram ```mermaid sequenceDiagram title Authorisation flow for Signicat APIs participant App as Your application participant S as Authorization server (/auth/open/connect/token) participant API as Signicat API box Signicat infrastructure participant S participant API end App->>+S: Request access token with API client credentials S-->>App: Return access token App->>API: Request resource with access token in 'Authorization' header Note right of API: 1. Verify access token2. Check permissions3. Check product is active API-->>App: Return protected resource ``` ::: ## 1. Initial preparations To use any Signicat API in your applications, you first need to sign up to the Signicat Dashboard. This allows you to configure an account, create API credentials and manage products. Before you start, make sure you have: - [Signed up to Signicat](/docs/) in the Signicat Dashboard. - Created an [organisation](/docs/dashboard/organisation-management/organisations.mdx), an [account](/docs/dashboard/organisation-management/accounts.mdx) and a [domain](/docs/dashboard/organisation-management/domains/) in the Signicat Dashboard. :::note Sandbox and production accounts We recommend that you create a sandbox account to test our services before going live. You must set up sandbox and production accounts separately. ::: ## 2. Get client credentials To authenticate against our APIs, you need to set up an API client with scope `signicat-api`. An API client consists of a `client_id`/`client_secret` pair. We recommend that you create one API client per API product, but this can depend on your use case or configuration. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**API clients**](https://dashboard.signicat.com/api-clients/). 2. Select **+ Add client**. 3. Enter a name for the client, then select **Create**. 4. You must have at least one client secret, so select **Add secret** to create one. This takes you to the **Secrets** tab on the client details page. 5. Select **+ Add secret** to create a secret. 6. Enter a name for the client secret, then select **Generate secret**. :::warning Store the client secret Make sure that you store the client secret in a secure place. This is the only time that you can view the client secret in clear text. If you do lose your client secret, then you can always generate another one. ::: :::tip Find the client ID An API client has an associated client ID visible in the client overview. For example, this could look something like `dev-round-apple-123`. ::: ## 3. Set permissions To complete the API client setup, you need to add the correct permissions for the API products that you intend to connect to with the client. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**API clients**](https://dashboard.signicat.com/api-clients/). 2. Select **Edit** next to the API client that you created. 3. On the API client page, navigate to the **Permissions** tab. :::note Cannot access the permissions tab? If you cannot access the **Permissions** tab, then you do not have the correct role to manage permissions for your organisation. To receive access, contact your organisation administrator or us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: 4. Select **+ Select product**. 5. Tick the box corresponding to the API product that you intend to use with this API client, then select **Update** to save the changes. :::note Cannot find the necessary permissions? This tab only shows permissions for our most used products. - To learn about which product permissions you need to add, see the [Most used product permissions](#most-used-product-permissions) section. - To learn about how to add any other permissions not shown here, see the [Advanced permissions](#advanced-permissions) section. ::: ### Most used product permissions The **Permissions** tab for your API client is designed for convenience and only displays the most used product permissions, shown in the table below. :::tip Cannot find the necessary permission? To learn about how to add any other permissions not shown below, see the [Advanced permissions](#advanced-permissions) section. ::: :::CustomTable{title="Permissions for most used products" columnWidths="25% 25% 50%"} | **Product** | **API** | **Permissions** | | :-- | :-- | :-- | | [ID Document and Biometric Verification](/docs/id-document-and-biometric-verification/) | [Assure REST API](/apis/id-document-and-biometric-verification/) | `Assure API` | | [eID and Wallet Hub](/docs/eid-hub/) | [Authentication REST API](/apis/eid-hub/) | `Authentication REST API` | | [Data Verification](/docs/data-verification/) | [Data Verification API](/apis/data-verification/) | `Data Verification for natural persons``Data Verification for organisations` | | [Digital Evidence Management (DEM)](/docs/digital-evidence-management/) | [Digital Evidence Management API](/apis/digital-evidence-management/) | `Digital Evidence Management (DEM)` | | [Mint](/docs/mint/) | [Mint API](/apis/mint/) | `Flow Editor` `Flow Viewer` **Note**: To set these permissions, you need to follow the steps in the [Advanced permissions](#advanced-permissions) section. | | [MobileID](/docs/mobile-identity/mobileid/) | [MobileID API](/apis/mobileid/) | `MobileID API` | | [MobileID](/docs/mobile-identity/mobileid/) | [MobileID Admin API](/apis/mobileid-admin/) | `MobileID Admin API` | | [ReuseID](/docs/reuseid/) | [ReuseID Onboarding API](/apis/reuseid-onboarding/) | `ReuseID Onboarding API` | | [ReuseID](/docs/reuseid/) | [ReuseID API](/apis/reuseid/) | `ReuseID MobileID Device API` `ReuseID Passkey API` | | [Electronic Signing](/docs/electronic-signing/) | [Sign API v2](/apis/electronic-signing/sign-api-v2/) | `Signature API` | | [Signicat IAM (SIAM)](/docs/siam/) | [SIAM SCIM API](/apis/siam/) | `Signicat IAM SCIM API` (`SiamEditor`) **Note**: To set `SiamViewer` or `SiamAdmin`, you need to follow the steps in the [Advanced permissions](#advanced-permissions) section. | ::: ### Advanced permissions You can manage all other advanced permissions for your API client using the **Access management** service in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Access management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions). 2. Click the **Edit** button beside the API/machine client that you want to update. 3. Click the **+ Add** button and select the desired role that you want to add. You can repeat this step to add multiple roles. 4. To confirm your changes, click the **Save** button. :::info Want to learn more? For more information, see the [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx) page. ::: ## 4. Obtain an access token You can now use the API client credentials to obtain an access token. To do this, you need to send a POST request using either of the following client authentication methods: - Explicit credentials (`client_secret_post`) - HTTP basic authentication (`client_secret_basic`) The table below shows an overview of the parameters required to build a request: :::CustomTable | **Name** | **Value** | | :-- | :-- | | Authorisation type | OAuth 2.0 | | Access Token URL | `https://api.signicat.com/auth/open/connect/token` | | Grant type | `client_credentials` | | Scope | `signicat-api` | | Client ID | The client ID that you obtained when you created the API client. | | Client secret | The client secret that you obtained when you created the API client. | ::: :::tip What tools can I use? You can obtain an access token using cURL, Postman, Node.js, Python, .NET, or whichever SDK or library you prefer. However, note that the OAuth 2.0 client credentials flow requires you to make only one POST request. ::: 1. Make a request using either of the client authentication methods: To obtain an access token using the `client_secret_post` authentication flow, you need to include your client credentials explicitly in the request payload. ```bash title="Example: Request for access token" curl --request POST https://api.signicat.com/auth/open/connect/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials' \ --data 'scope=signicat-api' \ --data 'client_id=sandbox-round-apple-123' \ --data 'client_secret=fakeCl13n7S3Cr3T1234567890' ``` To obtain an access token using the `client_secret_basic` authentication flow, you need to format your API client credentials as `client_id:client_secret`, then Base64 encode it. Next, substitute this string for `` in the authorisation header of the request. ```bash title="Example: Request for access token" curl --request POST https://api.signicat.com/auth/open/connect/token \ --header 'Authorization:Basic ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials' \ --data 'scope=signicat-api' ``` 2. If the request is successful, then a token response is returned to you. For example: ```http title="Example: Response with access token" HTTP/2 200 OK content-type: application/json; charset=UTF-8 cache-control: no-store, no-cache, max-age=0 { "access_token": "eyJh ... QifQ.eyJ ... hIOw", "expires_in": 600, "token_type": "Bearer", "scope": "signicat-api" } ``` :::info Token settings The default access token lifetime is set to 600 seconds. For more information about token lifetime and caching, see the [Access tokens](/docs/dashboard/connect-to-signicat-apis/advanced-settings/access-tokens.mdx) page. ::: ## 5. Make an API request Now that you have a valid access token, you can start making requests to your chosen Signicat API. To do this, you need to include the access token in the HTTP `Authorization` header with the `Bearer` scheme For example, the request below shows what a call to the [Authentication REST API](/apis/eid-hub/) could look like: ```http {4} title="Example: Request to Authentication REST API" GET /auth/rest/sessions/{id} HTTP/2 Host: api.signicat.com Accept: application/json Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw ``` :::warning HTTP requests Incoming HTTP requests to all of our APIs must meet specific requirements. For more information, see the [HTTP request requirements](/docs/dashboard/connect-to-signicat-apis/advanced-settings/http-request-requirements.mdx) page. ::: ## Next steps For more specific information on how to use Signicat API products, see our API reference or product documentation: * [**Signicat APIs**](/docs/dashboard/connect-to-signicat-apis/signicat-apis): Explore all Signicat API references * [**Signicat products**](/docs/products): Browse all Signicat products :::info Advanced API connection settings To learn about how to manage advanced API connection settings such as token lifetime and HTTP request requirements, see the [Advanced settings](/docs/dashboard/connect-to-signicat-apis/advanced-settings/) page. ::: --- ## Signicat APIs(Connect-to-signicat-apis) :::info How to connect to Signicat APIs To learn how to set up a connection to any Signicat API and start making requests, see our **Connecting to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). ::: ## Product APIs Our product APIs deliver core functionality for Signicat products. You can explore the API reference documentation for our products using the buttons below: ### Data Verification Verify customer data against different national and commercial data sources. * [**Data Verification API**](/apis/data-verification/): Verify information about natural persons or organisations ### Digital Evidence Management (DEM) Store transactional data or consent messages. * [**Digital Evidence Management API**](/apis/digital-evidence-management/): Securely capture, store and manage audit trail data ### eID and Wallet Hub Manage authentications with eIDs and wallets with the Signicat Authentication REST API. * [**Authentication REST API**](/apis/eid-hub/): Manage end-user authentications using our Authentication REST API ### Electronic Signing Create electronic signatures on contracts, declarations, forms and other documents. * [**Sign API v2**](/apis/electronic-signing/sign-api-v2/): Electronic signatures for both small to medium sized businesses and those within regulated industries * [**Enterprise Sign API**](/apis/electronic-signing/enterprise/): Electronic signatures for businesses within regulated industries * [**Express Signature API**](/apis/electronic-signing/express/): Electronic signatures for small to medium-sized businesses * [**Signicat Archive**](/apis/archive/): Securely store and retrieve signed documents ### ID Document and Biometric Verification Perform electronic identity verification (eIDV) with Assure API. * [**Assure API**](/apis/id-document-and-biometric-verification/): Perform electronic identity verification (eIDV) on end-users using our Assure REST API ### MobileID Implement strong customer authentication on mobile devices. :::note Want to use our next-generation API? The [ReuseID API](/apis/reuseid/) is our next-generation API for ReuseID services, including MobileID. - We recommend this for all customers, so that you can utilise the latest capabilities and improvements. - For existing customers, it is possible to use ReuseID and MobileID in parallel. ::: * [**MobileID API**](/apis/mobileid/): Manage identities and carry out mobile authentication operations * [**MobileID Admin API**](/apis/mobileid-admin/): Manage and administer your MobileID account ### Ongoing Monitoring Monitor changes to the identifying data of natural persons and organisations over time. * [**Person Monitoring API (Deprecated)**](/apis/person-monitoring/): Monitor information on natural persons over time * [**Ongoing Monitoring API**](/apis/ongoing-monitoring/): Monitor information on natural persons and organisations over time ### ReuseID Build your own reusable identities with ReuseID. * [**ReuseID Onboarding API**](/apis/reuseid-onboarding/): Use ready-made flows to onboard ReuseID identities and perform step-up operations * [**ReuseID API**](/apis/reuseid/): Manage identities and carry out ReuseID authentication operations ### Secure Share Create, manage and secure the files you share with others. * [**Secure Share API**](/apis/secure-share/): Share files securely with other people ### Signicat Mint Build custom business workflows and simplify your user journeys with a no-code platform. * [**Signicat Mint API**](/apis/mint/): Manage your flows and analyse your user journey reports ### User management Manage your end-users and create reusable identities globally with Signicat IAM. * [**Signicat IAM SCIM API**](/apis/siam/): Manage identity and access management for your platform ## Management APIs Our management APIs allow you to programmatically manage configurations that are typically handled in the Signicat Dashboard. You can explore the API reference documentation for managing configurations using the buttons below: :::note Note Our management APIs are not fully supported or covered by the same service-level agreements (SLAs) and uptime as our product APIs. This means that although they are maintained and functional, they are intended for developers who are looking to tackle a particular corner case, such as a custom integration. ::: ### Audit logs * [**Signicat Audit API**](/apis/audit-logs/): Query, view and filter activities in the audit logs ### Account management * [**Signicat Account Management API**](/apis/account-management/): Manage your organisations, accounts, and company information. Download invoices ### Domain management * [**Signicat Domain Management API**](/apis/domain-management/): Manage the domains for your account ### Events management * [**Signicat Events Management API**](/apis/events/): Create and manage subscriptions to events published by Signicat services ### OIDC Configuration API * [**OIDC Configuration API**](/apis/oidc-config/): Manage your OIDC client configuration (Advanced) ### Usage analytics * [**Signicat Usage API**](/apis/usage/): View analytics and insights on your API usage to track and optimise performance --- ## Error codes When you make a request to one of Signicat's APIs and an error occurs, a response with an error object is returned. If you have encountered an error, check the information on this page to investigate what might have caused the error. Specifically, the errors listed here are generic to all Signicat APIs. If you require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ## Error object A generic error object contains the following fields: :::CustomTable | Field name | Description | Format | Always returned | |------------|-------------|--------|-----------------| | `type` | URI to the documentation that describes the error. | String | | | `title` | A summary of the error type (this does not change between occurrences of the error). | String | | | `code` | A machine-readable string, indicating the error code. This is a constant. | String | | | `status` | The HTTP status code generated by the origin server (specific to this occurrence of the error). | HTTP status code | | | `detail` | An explanation of the error (specific to this occurrence of the error). | String | | | `invalidParams` | List of request parameters that have failed the validation. Contains the parameter name and the reason for validation failure. | String | | ::: :::note Additional fields Many APIs also define additional error fields to address and communicate product-specific errors. ::: ### Example responses An example response with a generic error object: ```json title="Example 1: Response with generic error object" { "type": "https://developer.signicat.com/docs/dashboard/error-codes/", "title": "Invalid authentication token.", "detail": "The authentication token provided is invalid. This may be due to an incorrect signature, expiration, or insufficient permissions.", "code": "invalid_token" } ``` When validation of request parameters fails, you receive an error message similar to: ```json title="Example 2: Response with failed validation of request parameters" { "type": "https://api.signicat.com/mobileid/core/openapi.json", "title": "Invalid request parameter", "code": "invalid_request_parameter", "status": 400, "traceId": "4bf239c088089f2bca77d3a413909f1d", "detail": "Your request body parameters have failed validation." "invalidParams": [ { "name": "userId" "reason": "userId cannot be null or empty" }, { "name": "deviceId" "reason": "deviceId cannot be null or empty" } ] } ``` :::details What does this example mean? In this example, we can determine that multiple request parameters have failed the validation. The `invalidParams` describes which request parameters have failed the validation, so that you can modify them to pass the validation. ::: ## Generic error codes :::CustomTable{columnWidths="40% 20% 40%"} | Error code | Error name | Description | | :-- | :-- | :-- | | `account_disabled` | Account disabled | The account is disabled and cannot be used for this operation. | | `account_does_not_exist` | Account not found | No account exists with the specified ID. | | `account_id_invalid` | Invalid account ID | The `accountId` is not in the correct format. | | `account_id_missing` | Missing account ID | No `accountId` was provided or could be found in the request. | | `invalid_account_id` | Invalid account ID | An invalid `accountId` was sent in the request. | | `invalid_redirect_url` | Invalid redirect URL | An unexpected `redirectUrl` was received by one of the components.**Note**: Internal API calls often have a response with a `redirectUrl`. | | `invalid_message_id` | Invalid message ID | The `messageId` is unknown or unexpected for the current user session. | | `invalid_pushback_url` | Invalid pushback URL | An invalid `pushBackUrl` was received by one of the components. **Note**: In a headless authentication flow, a `pushBackUrl` can optionally be provided in the request. | | `invalid_token` | Token validation error | The authentication token provided in the API request is invalid. This can happen if: The token's signature is incorrect. The token has expired. The token lacks the required permissions for this operation. | | `invalid_transaction_id` | Invalid transaction ID | The `transactionId` is unknown or unexpected for the current user session. | | `missing_permission` | Insufficient permission | You do not have the required permission to perform this operation on the target resource. | | `multiple_account_ids_provided` | Conflicting account IDs | The request contains multiple `accountId` values from different sources, such as headers, query parameters or a JWT. | | `not_found` | Not found | A HTTP 404 error. This means that the service you requested was not found. | | `product_not_enabled` | Product not enabled | The account does not have access to the requested product. | | `quota_usage_over_limit` | Quota limit exceeded | The rate of API requests exceeds the quota limit. This means that the response includes a [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) status code and a [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) header, which specifies how long (in seconds) to wait before retrying. **Note**: To request a quota increase, [create a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. | | `session_error` | Session error | A generic error that occurs in various Signicat backend components. Common causes are: The user session expires due to inactivity on pages of interaction. A public endpoint was called with wrong or unexpected session state. For example, calling a SAML ACS endpoint without first starting a login session from a service provider. | | `subject_account_permission_not_granted` | Permission Denied | The subject does not have the required permission for the specified account. | | `token_invalid_exp` | Token expired | The bearer token has expired. | | `token_invalid_issuer` | Invalid issuer | The bearer token's issuer in not valid. | | `token_invalid_nbf` | Token not yet valid | The bearer token is not valid yet. | | `token_invalid_not_a_jwt` | Invalid token format | The bearer token is not a valid JWT. | | `token_invalid_scope` | Invalid scope | The bearer token does not have the required `signicat-api` scope. | | `token_invalid_signature` | Invalid signature | The bearer token's signature is invalid. | | `token_missing` | Token missing | The request does not include a bearer token. | | `transaction_id_or_message_id_replayed` | Replay error | A Signicat backend component attempted to start a login session with a `messageId` or a `transactionId` that was used recently. | | `unexpected_error` | Unexpected error | An unexpected error occurred in a Signicat service and it is not handled properly. **Note**: This error is usually accompanied by an HTTP 500 response. | ::: ## Product-specific error codes All APIs can return generic error codes. There are also error codes specific to a service, such as an API product or a protocol. To learn more about error codes and descriptions specific to a service, visit the respective documentation: - [Data Verification](/docs/data-verification/error-codes/) - [eID and Wallet Hub - OIDC](/docs/eid-hub/oidc/oidc-error-codes/) - [MobileID API](/docs/mobile-identity/mobileid/error-codes/) - [Ongoing Monitoring](/docs/ongoing-monitoring/error-codes/) - [Sign API v2](/docs/electronic-signing/sign-api-v2/error-codes/) --- ## Glossary Here you will find a complete overview of all the most important terms used in the Signicat documentation and an explanation of each. ### Account Your organisation can have different types of accounts configured in the Signicat Dashboard, such as [production](#production) or [sandbox](#sandbox) (test) accounts. You can learn more about organisations and accounts in our [Organisation management](/docs/dashboard/organisation-management/) documentation. ### Authentication Authentication is about recognising a returning user. It is important to have an easy way to allow users to authenticate their identity each time they log in to a website, app or service. ### Authorisation Authorisation is about what an end-user is allowed to do. Whilst authentication allows an end-user to log in to an account, and thereby prove who they say they are, authorisation states what the end-user can now do, what kind of actions they are allowed to perform on your platform. Examples could be accessing an the HR system, or being allowed to enter new employees into the HR system. ### Certificate A certificate, or digital certificate, is an electronic document used to prove the ownership of a public key. The certificate includes information about the key, information about the identity of its owner (called the subject), and the digital signature of an entity that has verified the certificate's contents (called the issuer). For Signicat, certificates are either used to secure connections or as a means of logging in. ### Custom domain The custom domain using your organisation's own domain, `something.mycompany.com` for an [account](#account). See also [Signicat domain](#signicat-domain). ### Digital identity A digital identity is a person's identity in the digital space, meaning the sum of all digital information that can be linked to the person. Digital identity may also be used in a more narrow sense, for example to indicate the person's official identity attributes from an identity document or from an eID. ### eIDs The electronic identities (eIDs) used for identity proofing, user authentication, and electronic signing; for example BankID in Norway, MitID in Denmark and iDIN in the Netherlands. An eID is a means for a person to provide certain identity attributes, such as name, national identification number, date of birth, and so on. User attributes are stored by the eID and provided to your application on demand. Suppliers of eIDs are known as [Identity Providers (IdP)](#identity-provider). ### eID method See [eIDs](#eids). ### eIDAS eIDAS is a 2014 regulation of the European Parliament and Council on electronic identification and trust services for electronic transactions in EU/EEA. In the Netherlands, eIDAS is provided through the eHerkenning network. ### Electronic identification The process of using personal identification data in electronic form which uniquely represents either a natural or legal person, or a natural person representing a legal person. ### Electronic signature This is data in electronic form, which is attached to or logically associated with other data in electronic form, that is used by the signatory to sign. ### End-user In Signicat terms, the end-user is the person who ultimately uses a product. For example, in B2C signing, the end-user is not the company using the Sign solution to get their documents signed, but rather the private person who signs the document. ### EUDI Wallets EU Digital Identity Wallets (EUDI Wallets) let users prove who they are and share verified credentials like age and nationality across borders, with greater privacy, stronger security, and full EU-wide interoperability. By late 2027, regulated industries will be required to accept EUDI Wallets, especially for Strong Customer Authentication (SCA) to stay compliant. ### ID method See [eIDs](#eids). ### Identity method See [eIDs](#eids). ### Identity verification Identity verification is the act of determining the identity of an individual or organisation. This is something the individual or organisation do themselves. It can be done, for example, by using an eID (which has already been verified), or by scanning an identity document in conjunction with providing a selfie; but requirements may differ. Identity verification is useful for first time interactions with a customer, such as registration or onboarding. ### Identity provider An identity provider is the supplier of the eID. They are responsible for issuing the digital identities to a person. Customers can choose one or more of these identity providers to enable the end-user to log on to their online applications or services. Often, the identity provider and the eID share the same name, for example BankID in Norway and Sweden, but it might also be different. For example, Nets is the identity provider for MitID. ### Internal log This is a log that is used by Signicat's staff to analyse incidents. ### Know Your Customer (KYC) KYC is the process of a business verifying the identity of its clients. The objective of KYC guidelines is to prevent banks from being used, intentionally or unintentionally, by criminal elements for money laundering activities. ### Level of Assurance (LoA) Level of Assurance (LoA) refers to the degree of trust or confidence in the claimed identity of a person and how certain a [service provider](#service-provider) is about that person's claimed identity when using their eID to authenticate a service. {/*LoA refers to the difficulty one would have trying to use someone else's eID.*/} According to eIDAS regulations, there are three levels of assurance: Low, Substantial and High. 1. **Low**: Self-registration in a web-page, without any identity verification. 2. **Substantial**: Providing and verifying identity information and authentication by using a user name and a password and a one-time password sent to your mobile phone. 3. **High**: Registering in person in an office and authentication by using a smartcard, such as a National ID Card. ### National identification number National identification numbers are used by many countries' governments as a means of tracking their citizens, permanent residents and temporary residents for the purposes of work, taxation, government benefits, health care and many other government-related functions. This number usually appears on identity documents issued by these countries. ### Natural person A natural person, in legal terms, is defined as a living human being as opposed to a corporate body. ### Non-natural person A non-natural person is any corporate body, unincorporated firm, partnership or body with legal personality other than an individual. ### Onboarding Onboarding is the process of allowing end-users to sign up to an online service whereby a verification of that person is carried out using an eID. Onboarding refers to a first-time interaction with an end-user during the process of becoming a customer of a service and outlines what Signicat customers want to do to accept these new users to their service. ### One-Time Password (OTP) A One-Time Password is a randomly generated password, which is given to the end-user; for example as a text message (SMS), an email, a postal letter, by an app on a smartphone, or by a device. When entering the OTP, the end-user proves that they are in possession of the given item. This is typically used as part of a two-step authentication. ### Organisation This is the name of your company, business or organisation (one entity with a VAT number). Your organisation can have many [accounts](#account) in the Signicat Dashboard. You can learn more about organisations and accounts in the [Organisation management](/docs/dashboard/organisation-management/) documentation. ### Organisation number This is the number that identifies an organisation. The organisation number name varies from country to country ("Organisation Identification Number" in the Netherlands, "Enterprise number" in Belgium, "CVR" in Denmark, "Registration number" in Sweden). You can use this number in Signicat [Data Verification](/docs/data-verification/) to validate company information. ### Organisation Identification Number (OIN) An OIN is an Organisation Identification Number, or can also be called a Government Identification Number. You use it to identify yourself as an organisation. {/*## Parent organisation Reseller of Signicat, and option for organisations requiring multiple billing entities. This entity can also have a “parent organisation” to create a hierarchy that have depth n+1.*/} ### Politically exposed person (PEP) In financial regulation, a politically exposed person (PEP) is one who has been entrusted with a prominent public function. A PEP generally presents a higher risk for potential involvement in bribery and corruption by virtue of their position and the influence that they may hold. ### Product The name of a specific product in Signicat's portfolio. For an overview of products, see [All products](/docs/products.mdx). ### Product family A group of products in Signicat's portfolio. At Signicat, we organise our product according to the following product families: Identity Proofing, Trust Orchestration, Authentication and Electronic Signing. ### Production This is an [account](#account) type used in Signicat's production environment. It contains real data. The transactions are billed. ### Sandbox This is an [account](#account) type used in either Signicat's test or preproduction environments. It should only contain fake data. No transactions are billed. ### SDK A software development kit (SDK). ### Service provider A service provider (SP) is a customer of Signicat. This is the party that uses the digital identity service and provides the service to the end-user, such as a bank, insurance company, public body. SPs offer one or more identity methods (eIDs) on their app, portal or website so that end-users can identify or gain access to these online services. ### Signicat domain The Signicat subdomain for an account `accountname.app.signicat.com` (production). All accounts can have a Signicat subdomain. See also [Custom domain](#custom-domain). ### Single logout (SLO) With single log-out (SLO), an end-user can log out of all active sessions (even over multiple different service providers) by sending a single log-out request to the application of the service provider. SLO can be initiated by the end-user or the service provider, or in some cases by the IdP. SLO is session- and token-based. For more information, see [eID and Wallet Hub - SLO](/docs/eid-hub/oidc/oidc-implementation.mdx#single-log-out-slo) ### Single sign-on (SSO) With single sign-on (SSO), an end-user can log in to services once and access them without having to re-enter authentication factors. This only applies to services that are connected to the same SSO session. SSO is session- and token-based. For more information, see [eID and Wallet Hub - SSO](/docs/eid-hub/concepts/single-sign-on.mdx) ### Time-based OTP (TOTP) A time-based OTP service generates one-time passwords (OTP) based on time, whereby the user has a certain, limited amount of time to enter the time-based OTP. Typically, the user relies on a smartphone app for generates time-based OTP codes. One such application is the Google Authenticator. ### Two-factor authentication (2FA) Also referred to as two-step verification or dual-factor authentication, two-factor authentication is the process in which end-users must provide two different authentication factors to verify themselves. 2FA is a secure process that helps protect both an end-user's credentials and the resources the user can access. --- ## Signicat Dashboard The Signicat Dashboard gives you the tooling and infrastructure to onboard customers, sign agreements, manage user logins and automate identity workflows, all whilst staying compliant across markets. :::info Take me to the [Signicat Dashboard](https://dashboard.signicat.com/)! ::: ## Get to know the Dashboard If you specified an organisation name in the registration form when signing up to the Signicat Dashboard, then we automatically create the resources below for you, ready for when you log in the first time. These resources allow you to start building your integration with Signicat products in a test environment: :::CustomTable{tableName="Your resources in the Signicat Dashboard" } | **Resource name** | **Description** | | :-- | :-- | | [Organisation](/docs/dashboard/organisation-management/organisations.mdx) | This matches the organisation name that you provided in the registration form. | | [Sandbox account](/docs/dashboard/organisation-management/accounts.mdx) | This allows you to try out our services using test data. | | [Domain](/docs/dashboard/organisation-management/domains/) | This is associated with your sandbox account, and is required for using certain products. | ::: :::details I did not add an organisation name in the registration form If you did not specify an organisation name in the registration form, then these resources are not automatically set up for you. To set them up manually: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com/), then click the **Create organisation** button. 2. Enter your organisation name, then click the **Create** button. 3. To add an account: 1. Go to **Signicat Dashboard** > **Organisation**. 2. Click the **+ Add account** button, then follow the on-screen instructions. 4. To add a domain: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/). 2. Click the **+ Add domain** button, then follow the on-screen instructions. ::: :::info Going live with a production account To configure your organisation for a live integration in production, you need to undertake necessary preparations such as registering your company details. You can learn how to do this in the [Organisation management](/docs/dashboard/organisation-management/organisations.mdx) documentation. ::: ## Tutorial video This video shows you how to navigate and use the Signicat Dashboard. Explore topics such as: - How to invite users. - How to configure your product. - How to view your statistics and invoices. ## Next steps * [**Organisations**](/docs/dashboard/organisation-management/organisations): Learn how to add, manage and delete organisations * [**Accounts**](/docs/dashboard/organisation-management/accounts): Learn how to create and delete sandbox and production accounts * [**Domains**](/docs/dashboard/organisation-management/domains/): Learn how to add and manage standard Signicat domains and custom domains * [**Connect to Signicat APIs**](/docs/dashboard/connect-to-signicat-apis): Learn how to connect to Signicat APIs * [**Logging in**](/docs/dashboard/logging-in/): Learn how to manage your login methods for the Signicat Dashboard --- ## IP addresses and DNS This page contains crucial information about connecting to Signicat services. The only supported method for service consumption is through the Domain Name System (DNS). While we provide our IP address ranges for firewall configuration, a proper understanding of our DNS-first policy is essential for ensuring stable and reliable integration. :::warning Important: How our infrastructure changes It is important to understand the two ways our network infrastructure can change: * **Service routing (without prior notice):** We may shift services between the IP addresses (listed on this page) to perform maintenance or manage load at any time. This is the main reason why it is required to use the DNS and follow the TTLs. * **IP range updates (with prior notice):** We rarely add new IP addresses or remove old ones. If this happens, we notify you in advance. The IP ranges on this page are provided **exclusively** for configuring your firewall's allowlist. They must not be used for service connections. ::: ## DNS requirements Signicat services are designed to be accessed at their respective domain names (for example, `api.signicat.com`), leveraging DNS for robust, flexible and secure connectivity. Our infrastructure is dynamic, and IP addresses can change without prior notice. To further enhance security, all Signicat domains are configured with DNSSEC (Domain Name System Security Extensions), which ensures that the DNS records you receive from our domain names are authentic and have not been tampered with. **Directly connecting to IP addresses or failing to respect DNS TTLs will lead to service disruptions.** It is critical that all clients and systems consuming Signicat services properly resolve our domain names and **strictly adhere to the Time-To-Live (TTL) values** specified in our DNS records. Failure to do so will lead to connectivity issues, especially during planned maintenance, infrastructure updates, or disaster recovery scenarios. ### Best practices * **Always** use the provided domain names to connect to Signicat services. * **Ensure** you configure your DNS resolvers and client applications to honour the TTL values of our DNS records. * **Avoid** hardcoding IP addresses in your configurations. * **Use** a DNSSEC-validating resolver. * If you experience connectivity issues, **verify** your DNS resolution and cache behaviour, as a first step for troubleshooting. ## IP addresses for firewall configuration ### Incoming traffic All incoming traffic to Signicat passes through a Loadbalancer available at the following IP addresses: :::CustomTable{columnWidths="33% 33% 33%"} | Service | IPv4 addresses | IPv6 addresses | | :----------- | :--------------- | :------------- | | Loadbalancer | `34.117.2.96/30` | `2a14:b580::/48` | | CDN | `34.149.131.77` | `2600:1901:0:a1f1::` | ::: ### Outgoing traffic Outgoing traffic from Signicat originates from the `NAT-main` range. In a disaster recovery scenario, we will redirect this traffic to the `NAT-disaster-recovery` range. :::CustomTable{columnWidths="50% 50%"} | Service | IPv4 range | | :----------- | :--------------- | | NAT-main | `35.234.168.128/28` | | NAT-disaster-recovery | `34.88.194.16/28` | ::: ## Additional resources - To learn more about our networks and infrastructure, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. - To view the real-time status of our platform and services, check out our [Status page](https://status.signicat.com/). --- ## Log in to Signicat with external identity providers # External identity providers You can log in to the Signicat Dashboard using external identity providers (IdPs). These are third-party IAM platforms, like Microsoft Entra ID and Okta. By connecting your external identity provider, you and your team can access the Signicat Dashboard with single sign-on (SSO) by using your existing corporate login credentials. As an administrator, you can manage user access, team logins and permissions directly from your identity and access management (IAM) platform. Integrating an external identity provider offers several key benefits: - **Centralised access control**: Manage user access from your existing IAM platform. - **Consistent user experience**: Maintain your enterprise policies and multi-factor authentication (MFA) settings. - **Simplified logins**: Allow your team to access the Signicat Dashboard without needing to create separate user profiles. ## Choose your identity provider To learn how to set up, configure and log in with third-party identity providers, make a selection using the buttons below: * [**SSO with Microsoft Entra ID**](/docs/dashboard/logging-in/external-identity-providers/microsoft-entra-id): Learn how to configure and log in with Microsoft Entra ID. * [**SSO with Okta**](/docs/dashboard/logging-in/external-identity-providers/okta): Learn how to configure and log in with Okta. --- ## Set up Signicat Dashboard login with Microsoft Entra ID You can set up single sign-on (SSO) for the Signicat Dashboard using Microsoft Entra ID as your external identity provider. This setup allows you to manage user authentication centrally in Microsoft Entra ID while giving your team secure access to Signicat services. :::note Production accounts only The external identity provider feature is only available for production accounts in the Signicat Dashboard. ::: The Signicat Microsoft Entra ID integration allows you to use your Microsoft identity platform as your identity provider to centralise user management operations for your organisation in the Signicat Dashboard. When you configure Microsoft Entra ID as an external identity provider, your team can use their existing work accounts to log in securely to the Signicat Dashboard, without having to set up new user profiles. ## Get started :::info How to activate Microsoft Entra ID as an external identity provider To enable Microsoft Entra ID as an external identity provider, you need to request access from an onboarding manager by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Prerequisites Before you begin the integration process, ensure you have the necessary permissions in Microsoft Entra ID. You need a Microsoft Entra ID user account with one of the following administrator roles: - Global Administrator - Application Administrator - Cloud Application Administrator Confirm that you have one of these required roles inside your Microsoft Entra tenant before you proceed with the integration. ## Register an application in Microsoft Entra ID To set up the integration, you need to register a new OpenID Connect (OIDC) application within the Microsoft Entra admin center. This application establishes the trust relationship between Microsoft Entra ID and the Signicat Dashboard. 1. Log in to the [Microsoft Entra admin center](https://entra.microsoft.com/). 2. Browse to **Entra ID** > **App registrations** and select **New registration**. 4. Enter a clear name for your application (for example, `Signicat Dashboard SSO`). 5. Choose your preferred supported account types (typically **Single tenant only - \** for most applications). 6. Under the **Redirect URI** section, set the platform dropdown to **Web** and enter the Signicat callback URL. This is `https://login.signicat.com/idps/oidc-vendor/response`. 7. Click the **Register** button to create the application. 8. On the application's **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID** values and save them. You will need them shortly. For an overview of the steps, see the official documentation to [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). ### Add a secret to your application 1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), in **App registrations**, select your application. 2. Select **Certificates & secrets** > **Client secrets** > **New client secret**. 3. Add a description for your client secret. 4. Select an expiration for the secret or specify a custom lifetime. 5. Select **Add**. 6. Record the client secret **Value**. You will need it shortly. This secret value is never displayed again after you leave this page. For an overview of the steps, see the official documentation to [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret). ## Configure SSO in the Signicat Dashboard To configure SSO with Microsoft Entra ID in the Signicat Dashboard, you must contact your onboarding manager or the Signicat support team by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. When you submit your ticket, include the following authentication details from your newly registered Microsoft Entra ID application: :::CustomTable | Field name | Value | Description | | :--- | :--- | :--- | | **CLIENT_ID** | Your Microsoft Entra Application (client) ID | The unique client identifier that you copied from your application overview. | | **CLIENT_SECRET** | Your Microsoft Entra Client Secret | The secret key value that you generated in the certificates and secrets section. | | **TENANT_ID** | Your Microsoft Entra Directory (tenant) ID | The directory ID of your Microsoft Entra tenant where the application is registered. | ::: ## Log in with Microsoft Entra ID SSO Once Signicat configures your integration, you can test the authentication flow to confirm that Microsoft Entra ID successfully handles single sign-on. 1. Open a new private or incognito browser window. 2. Navigate to the [Signicat IDP Selector page](https://dashboard.signicat.com/login-idp-selector). 3. Select **Log in with Microsoft Entra ID** from the list of available external identity providers. A screenshot of Signicat's login page displaying the list of External Identity Providers. 4. Enter your work email address associated with your Microsoft Entra tenant. 5. Select **Log in**. 6. Enter your credentials in the Microsoft login portal when redirected, and complete any required multi-factor authentication (MFA). 7. Confirm that Microsoft successfully authenticates you and redirects you back to the Signicat Dashboard. ## Assign Microsoft Entra ID groups to Signicat roles To enable automated provisioning, you need to configure role mapping between your Microsoft Entra ID groups and specific roles in the Signicat Dashboard. Signicat uses this role mapping to assign the correct permissions to new team members automatically. Role mapping across platforms ensures that your team members automatically receive the correct permissions when they log in to the Signicat Dashboard for the first time. ### 1. Manage Microsoft Entra ID groups Before defining the mapping to Signicat roles, you need to add and define user groups in the Microsoft Entra ID platform. To learn about how to manage user groups, visit the official documentation to [Manage Microsoft Entra groups and group membership](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-manage-groups). ### 2. Configure Signicat roles and mapping After you have created and configured your user groups in the Microsoft Entra ID platform, you can define the mapping between those groups and the roles supported by the Signicat Dashboard. To learn about the roles and permissions for the Signicat Dashboard, visit the [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions/#which-roles-to-assign) documentation. After you have identified the roles to assign to your team, Signicat Support can help you configure your role mapping. To do this, you need to [create a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::note Note In your request, you must provide a list of the Microsoft Entra ID groups, with their respective **Object Id** values, that you want to map to Signicat roles. ::: ## User management with the SCIM REST API You can edit the roles, permissions and profiles of your existing users after they have already onboarded to the Signicat Dashboard. To modify the configuration of existing users, you need to use the **Signicat IAM SCIM API**. This REST API allows you to manage user identity and access programmatically across your platforms by performing the following operations: - Get user profiles and attributes. - Update users and their attributes (such as modifying roles for existing, onboarded users). - Deactivate users. - Lock and unlock user access. To learn more about managing your existing users programmatically, see the [Signicat IAM SCIM API](/apis/siam/) reference documentation. --- ## Set up Signicat Dashboard login with Okta You can set up single sign-on (SSO) for the Signicat Dashboard using Okta as your external identity provider. This setup allows you to manage user authentication centrally in Okta while giving your team secure access to Signicat services. :::note Production accounts only The external identity provider feature is only available for production accounts in the Signicat Dashboard. ::: The Signicat Okta integration allows you to use Okta as your identity provider to centralise user management operations for your organisation in the Signicat Dashboard. When you configure Okta as an external identity provider, your team can use their existing Okta credentials to log in securely to the Signicat Dashboard, without having to set up new user profiles. ## Get started :::info How to activate Okta as an external identity provider To enable Okta as an external identity provider, you need to request access from an onboarding manager by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Prerequisites Before you begin the integration process, ensure you have the [necessary permissions in Okta](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm). You need an Okta user account with one of the following administrator roles: - Super Admin - Org Admin - Group Admin To check your user permissions in Okta, follow these steps: 1. Log in to your Okta Admin Console. 2. Select **Directory** > **People** in the left menu. 3. Select your user profile from the list. 4. Select the **Admin roles** tab. Confirm that you have one of the required roles before you proceed with the integration. ## Create an Okta application Once you have the required permissions, you need to create a new OpenID Connect (OIDC) application in Okta to represent the Signicat Dashboard. 1. Log in to your Okta Admin Console. 2. Select **Applications** > **Applications** in the left sidebar menu. 3. Select **Create App Integration**. 4. Choose **OIDC - OpenID Connect** as your sign-in method, then select **Next**. 5. Select **Web Application** as your application type, then select **Next**. 6. Enter a clear name in the **App integration name** field (for example, `Signicat Dashboard SSO`). 7. Under the **Grant type** section, select the **Authorization Code** checkbox. 8. In the **Sign-in redirect URIs** field, enter the Signicat Dashboard callback URL. This is `https://login.signicat.com/idps/okta/response`. 9. Under the **Assignments** section, select the Okta user groups that require access to the Signicat Dashboard. 10. Select **Save** to create the application. 11. Navigate to the **General** tab, copy the **Client ID** and **Client Secret**, and save them securely for the next phase. :::note Post-logout redirect URL If your setup requires a post-logout Redirect URI, you can use `https://dashboard.signicat.com/signout-callback-oidc`. ::: ## Configure SSO in the Signicat Dashboard To configure SSO with Okta in the Signicat Dashboard, you need to contact your onboarding manager or the Signicat support team by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. When you submit your ticket, include the following authentication details from your newly created Okta application: :::CustomTable | Field name | Value | Description | | :--- | :--- | :--- | | **Issuer URL** | Your custom Okta domain URL (for example, `https://your-organisation.okta.com`) | This tells Signicat where to direct your team members for authentication. | | **Client ID** | Your Okta Client ID | The unique identifier of your application that you copied from your Okta application. | | **Client Secret** | Your Okta Client Secret | The secret key that you copied from your Okta application. | | **Scopes** | `openid`, `profile`, `email`, `phone`, `groups`, `address` | These permissions allow Signicat to retrieve basic user details from Okta and map them to your user profiles in the Signicat Dashboard. | ::: ## Log in with Okta SSO Once Signicat configures your integration, you can test the authentication flow to confirm that Okta successfully handles single sign-on. 1. Open a new private or incognito browser window. 2. Navigate to the [Signicat IDP Selector page](https://dashboard.signicat.com/login-idp-selector). 3. Select **Log in with Okta** from the list of available external identity providers. A screenshot of Signicat's login page displaying the list of External Identity Providers. 4. Enter your work email address associated with your Okta domain. 5. Select **Log in**. 6. Enter your credentials in your Okta login portal when redirected. 7. Confirm that Okta successfully authenticates you and redirects you back to the Signicat Dashboard. ## Assign Okta groups to Signicat roles To enable automated provisioning, you need to configure role mapping between your Okta groups and specific roles in the Signicat Dashboard. Signicat uses this role mapping to assign the correct permissions to new team members automatically. Role mapping across platforms ensures that your team members automatically receive the correct permissions when they log in to the Signicat Dashboard for the first time. To learn about the roles and permissions for the Signicat Dashboard, visit the [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions/#which-roles-to-assign) documentation. After you have identified the roles to assign to your team, Signicat Support can help you configure your role mapping. To do this, you need to [create a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::note Note In your request, you must provide a list of the Okta groups that you want to map to Signicat roles. ::: ## User management with the SCIM REST API You can edit the roles, permissions and profiles of your existing users after they have already onboarded to the Signicat Dashboard. To modify the configuration of existing users, you need to use the **Signicat IAM SCIM API**. This REST API allows you to manage user identity and access programmatically across your platforms by performing the following operations: - Get user profiles and attributes. - Update users and their attributes (such as modifying roles for existing, onboarded users). - Deactivate users. - Lock and unlock user access. To learn more about managing your existing users programmatically, see the [Signicat IAM SCIM API](/apis/siam/) reference documentation. --- ## Logging in The Signicat Dashboard supports multiple authentication methods, allowing you to log in using: - A username and password - Multi-factor authentication (MFA) with a time-based one-time password (TOTP) - A passkey - External identity providers (IdPs) with single sign-on (SSO) :::note Note A username and password is the standard method for logging in to your Signicat user profile. MFA is required if your user profile has access to one or more production accounts. ::: To learn how to set up, configure and log in with them, make a selection using the buttons below: * [**Username and password**](/docs/dashboard/logging-in/username-and-password): Learn about logging in with a username and password * [**MFA with TOTP**](/docs/dashboard/logging-in/multi-factor-authentication): Learn about logging in with multi-factor authentication and TOTP * [**Passkeys**](/docs/dashboard/logging-in/passkeys): Learn about logging in with a passkey * [**External IdPs with SSO**](/docs/dashboard/logging-in/external-identity-providers): Learn about logging in with SSO --- ## Multi-factor authentication (MFA) Multi-factor authentication (MFA) with time-based one-time passwords (TOTP) provide an extra layer of security for your Signicat user profile. When enabled, you must enter a 6-digit code from an authenticator app such as _Google Authenticator_ or _Microsoft Authenticator_ after entering your password. :::note Mandatory MFA If your user profile has access to one or more production accounts, then you are required to configure multi-factor authentication (TOTP) during the login process to proceed. ::: On this page, you can learn about: - How to set up MFA for your Signicat user profile. - How to log in to the Signicat Dashboard using MFA. - How to remove MFA from your Signicat user profile. ## How to set it up :::note Before you start Before you can set up MFA, you must first log in to the Signicat Dashboard using your [username and password](/docs/dashboard/logging-in/username-and-password.mdx). ::: To set up this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com), then click your user icon in the top navigation bar. 2. From the dropdown menu, select **Manage profile**. You are now on the [Personal info](https://dashboard.signicat.com/user-profile/personal-info) page. 3. In the **Multi-factor authentication** section, click the **Set up** button. 4. In the dialog box, enter the password for your Signicat user profile, then click the **Verify** button. 5. Using your preferred authenticator app on your mobile device, scan the QR code shown in the dialog box in the Signicat Dashboard. :::tip Enter key manually If you are having issues with the QR code, then you can also enter the key manually using the link beneath it. ::: 6. In the dialog box, enter the 6-digit code from the authenticator app on your mobile device, then click the **Continue** button. 7. Use the **Download** or **Copy** buttons to save the recovery codes in a secure location. :::tip What are recovery codes? If you lose your mobile device used for two-factor authentication, then you can use these recovery codes to log in to your user profile instead of the 6-digit verification code from the authenticator app. Each recovery code can only be used once. ::: 8. Tick the **I have saved my recovery codes** box, then click the **Confirm** button. ## How to log in using MFA To log in using this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com). 2. On the login page, enter your **Email address** and **Password** in the respective fields. 3. Click the **Log in** button. 4. Enter the verification code from your configured authenticator app. 5. Optionally, you can tick the box to remember your device for 7 days. :::tip What does this mean? This means that you do not have to enter a verification code the next time you log in within this timeframe. ::: 6. Click the **Next** button. ## How to remove MFA To remove this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com), then click your user icon in the top navigation bar. 2. From the dropdown menu, select **Manage profile**. You are now on the [Personal info](https://dashboard.signicat.com/user-profile/personal-info) page. 3. In the **Multi-factor authentication** section, click the **Remove** button. 4. In the dialog box, enter your current password, then click the **Confirm** button. --- ## Passkeys Passkeys are a safe and easy alternative to passwords. Once you have registered a passkey, you can log in to your Signicat user profile using: - Your biometric sensor, such as a fingerprint or facial recognition. - Your PIN or pattern. :::warning Important To use passkeys, you must have a supported device and browser. Most modern operating systems (Windows, macOS, iOS, Android) and browsers (Chrome, Safari, Edge, Firefox) support passkeys. ::: On this page, you can learn about: - How to set up a passkey for your Signicat user profile. - How to log in to the Signicat Dashboard using a passkey. - How to remove a passkey from your Signicat user profile. ## How to set it up :::note Before you start Before you can register a passkey, you must first log in to the Signicat Dashboard using your [username and password](/docs/dashboard/logging-in/username-and-password.mdx). ::: To set up this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com), then click your user icon in the top navigation bar. 2. From the dropdown menu, select **Manage profile**. You are now on the [Personal info](https://dashboard.signicat.com/user-profile/personal-info) page. 3. In the **Passkey** section, click the **+ Add passkey** button. 4. In the dialog box, enter the password for your Signicat user profile, then enter a name for the passkey. 5. Click the **Continue** button. 6. Follow the on-screen instructions provided by your browser or operating system to create and save your passkey. 7. Once successfully completed, a dialog box appears in the Signicat Dashboard, confirming that the passkey has been added. You can click the **Close** button to dismiss this. ## How to log in To log in using this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com). 2. On the login page, select **Sign in with passkey**. 3. Follow the on-screen instructions provided by your browser or operating system to authenticate using your biometric sensor, PIN, or pattern. :::tip Authentication fallback If you are unable to use your passkey, then you can choose to log in using another method, such as with your standard password or an email-based login. For example, this could happen if you are on a new device or your biometric sensor fails. ::: ## How to remove a passkey To remove this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com), then click your user icon in the top navigation bar. 2. From the dropdown menu, select **Manage profile**. You are now on the [Personal info](https://dashboard.signicat.com/user-profile/personal-info) page. 3. In the **Passkey** section, click the bin icon beside the passkey that you would like to remove. 4. In the dialog box, enter your current password, then click the **Remove** button. --- ## Username and password A username and password is the standard method for logging in to your Signicat user profile. On this page, you can learn about: - How to log in to the Signicat Dashboard using your login credentials. - How to update your login credentials. - How to reset a forgotten password using a password reset email. ## How to log in To log in using this authentication method, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com). 2. On the login page, enter your **Email address** and **Password** in the respective fields. 3. Click the **Log in** button. ## How to update your login credentials To update your login credentials, you need to: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com), then click your user icon in the top navigation bar. 2. From the dropdown menu, select **Manage profile**. You are now on the [Personal info](https://dashboard.signicat.com/user-profile/personal-info) page. 3. In the **Login credentials** section, click the **Edit** button beside the credential that you would like to update. :::tip Tip It is possible to update your email address, username and password. ::: 4. In the dialog box, enter your current password and the updated credential in the provided fields. 5. Click the **Save** / **Continue** button. ## How to reset a forgotten password If you have forgotten your password, then we can send a reset link to your email address. To do this: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com). 2. On the login page, click the **Forgot your password?** link. 3. Enter your email address associated with your Signicat user profile, then click the **Send reset link** button. 4. Open your email and locate the password recovery email from Signicat, then click the **Reset password** button to visit the password reset page. 5. Enter your new password in the provided fields. --- ## Accounts An account is a logical entity to group and separate resources and billing within your organisation. You can think of accounts similarly to how the departments within your company are distinct units. Accounts come in different types to allow you to distinguish between test and production environments. The information in each account is stored separately, which may be an important consideration depending on your needs. Having separate accounts can be helpful for billing purposes, for example, if two departments within your company are using Signicat products. It also allows you to thoroughly control how each account is used. :::info Try it in the Signicat Dashboard To manage your accounts in the Signicat Dashboard, go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/) and select an account. ::: ## Account types When creating an account, you can choose between a [sandbox account](/docs/dashboard/glossary.mdx#sandbox) and a [production account](/docs/dashboard/glossary.mdx#production). **Sandbox accounts** Opt for a sandbox account if you wish to test your integration with any Signicat product using fake data. A sandbox account is a trial environment where you can play around with and test your integration. **Production accounts** Production accounts contain real data and allow you to purchase products in the Marketplace. You must use a production account to integrate your application with Signicat in a live environment. :::warning Note It is not possible to edit the account type after creation. However, you can create multiple accounts under the same organisation. ::: ## Create an account To create an account in the Signicat Dashboard, do the following: 1. Log in to the [Dashboard](https://dashboard.signicat.com/). 2. Select the name of your organisation at the top left of the screen and then select **Manage**. 3. Under **Organisation management**, select **Add Account**. 4. Enter the name of your account under **Account Name**. 5. Tick the box of the account type you wish to create, either **Sandbox account** or **Production account**. 6. Select **Create** to create the new account. Create account screen ## Delete an account To delete an account in the Signicat Dashboard, do the following: 1. Log in to the [Dashboard](https://dashboard.signicat.com/). 2. Select the name of your organisation at the top left of the screen and then select **Manage**. 3. Under **Organisation management**, select an existing account. 4. In the **Account management** page, expand **Account actions** and select **Delete**. 5. To restore the account, select **Undelete**. 6. To permanently delete the account, select **Permanently delete**. You cannot undo this operation. ## Next steps Before you can get started with an integration, many products require that you add at least one domain. * [**Domains**](/docs/dashboard/organisation-management/domains/): Learn how to add and manage standard Signicat domains and custom domains --- ## Business details As a part of the company registration process, you need to add the business details for your company in the Signicat Dashboard so that you are able to use our services in production. :::info Why do we need this? We collect this information to enhance your business service and meet regulatory and financial partner requirements. ::: To add your business details: 1. Go to **Signicat Dashboard** > **Organisation** > [**Business details**](https://dashboard.signicat.com/org-mgmt/company-registration/business-details/). 2. In the **Country** dropdown menu, select the country where your company is registered. 3. In the **Company registration number** field, enter the registration number for your company. Ensure that this accurately matches the number in the relevant country's company register. 4. To fetch available details, click the **Lookup** button. :::note Note Some countries do not support lookup functionality. If your country is not supported, then you need to manually enter all of your business details into the available fields. ::: 5. In the **Industry** dropdown menu, select the industry that best matches your company. 6. In the **Operates in** dropdown menu, select the country where your company conducts business. If your company operates in multiple countries, then you must add every country that applies. 7. Review that the company address is correct. If not, then you can make changes by clicking the **Edit** button. 8. To finalise your changes, click the **Continue** button. :::note Success! You have now registered your business details. ::: --- ## Company registration Before you can start using our products, you need to complete the company registration process in the Signicat Dashboard. To learn how to do this, you can follow the guides listed below: * [**Business details**](/docs/dashboard/organisation-management/company-registration/business-details): Learn how to enter the business details for your company * [**Key contacts**](/docs/dashboard/organisation-management/company-registration/key-contacts): Learn how to add key contacts in your organisation * [**Payment method**](/docs/dashboard/organisation-management/company-registration/payment-method): Learn how to add a payment method for your organisation --- ## Key contacts As a part of the company registration process, you need to add the following three key contacts for your organisation in the Signicat Dashboard: - Commercial owner - Main technical contact - Financial contact :::info Why do we need this? Adding key contacts automatically invites them to the Signicat Dashboard with the correct roles. This then means that important information can be communicated to the appropriate people in your organisation. ::: To add your key contacts: 1. Go to **Signicat Dashboard** > **Organisation** > [**View key contacts**](https://dashboard.signicat.com/org-mgmt/company-registration/contacts/). 2. For each respective contact, click the **Add** button to assign a contact. 3. Complete all fields on the page: - **First name** - **Last name** - **Business email address** - **Phone number** with correct country code prefix. :::tip Tip If the contact is you, then you can enable the **Autofill with my details** toggle button at the top of the page. This populates all fields with your contact details that we have available in the system. ::: 4. To finalise your changes for a particular contact, click the **Continue** button. 5. Once you have added all key contacts, click the **Continue** button on the **Contacts** overview page. :::note Success! You have now added your key contacts. ::: --- ## Payment method As a part of the company registration process, you need to add the payment method in the Signicat Dashboard that is used to bill your organisation. To add a new card for your payment method: 1. Go to **Signicat Dashboard** > **Organisation** > [**Payment method**](https://dashboard.signicat.com/org-mgmt/company-registration/payment-method/). :::tip Tip If you have already added a card previously, then you may need to click the **Add new card** button once you are on the **Payment method** page. ::: 2. Complete all fields on the page with your card details: - **Name on the card** - **Card number** - **Expiration** - **CVC** 3. To proceed, you need to confirm the following statements by ticking the corresponding boxes: - _I confirm that this card will be used to perform payments, including monthly, for my organisation._ - _I confirm that I have the right to use the data I entered and I am solely accountable for its accuracy_. 4. To finalise your changes, click the **Save card** button. :::note Success! You have now added a new card as a payment method for your organisation. ::: --- ## Custom domain A custom domain allows you to create a branded experience for your end-users, as you can customise the entire domain. This means that there is no Signicat branding in the URL. Your integration might also require a custom domain for security reasons. A custom domain requires an SSL/TLS certificate. ```https title="Example: Custom domain" ..com ``` ## Certificate type When you add a custom domain to your account, you can choose between a **Signicat-managed certificate** or a **Self-managed certificate**. These SSL/TLS certificate management options are described in the table below: :::CustomTable{tableName="Overview of certificate types" columnWidths="25% 75%"} | **Certificate type** | **Description** | | :-- | :-- | | Signicat-managed certificate | You only need to configure your DNS settings to point to the custom domain. Signicat handles certificate management and renewal. | | Self-managed certificate | You manage, provision, and renew your own SSL/TLS certificates. Self-managed certificates can be any of the following certificate types: Domain Validation (DV)Organization Validation (OV)Extended Validation (EV) | ::: ## Set up a custom domain To learn how to set up a custom domain for your account, make a selection using the buttons below: * [**Custom domain (Signicat-managed certificate)**](/docs/dashboard/organisation-management/domains/custom/signicat-managed-certificate): Learn how to set up a custom domain with a Signicat-managed certificate * [**Custom domain (Self-managed certificate)**](/docs/dashboard/organisation-management/domains/custom/self-managed-certificate): Learn how to set up a custom domain with a self-managed certificate ## Switch the certificate type To learn how to switch the certificate type for your custom domain, see the guide below: * [**Switch certificate**](/docs/dashboard/organisation-management/domains/custom/switch-certificate-type): Learn how to switch the certificate type for your custom domain --- ## Self-managed certificate When you choose a **custom domain** that uses a **self-managed certificate**, you have more control over your certificates, such as choosing a Certificate Authority (CA), the type of certificate, and renewal times. However, self-managed certificates require preparation. You must handle the following aspects: - Obtaining and managing SSL/TLS certificates. - Configuring your server, proxy and security settings to ensure secure communication. This may include setting up and configuring a reverse proxy to route traffic to Signicat. - Handling certificate renewals and updates (Signicat notifies you when your certificate is about to expire). - Monitoring and addressing any SSL/TLS errors or performance issues related to your custom domain. :::tip Our recommendation We recommend that you set up your custom domain during the development phase, before you go to production. ::: ## How to set up a custom domain (self-managed certificate) To add a custom domain using a self-managed certificate, you need to complete the following steps: 1. Add your domain name in the Signicat Dashboard. 2. Configure the CNAME record with your DNS provider, so that traffic targeting your custom domain is forwarded to our servers. 3. Create a Certificate Signing Request (CSR) in the Signicat Dashboard. 4. Purchase an SSL/TLS certificate with a certificate authority (CA), using the CSR that you created in the previous step. 5. Upload the SSL/TLS certificate in the Signicat Dashboard that you purchased in the previous step. To learn how to complete each step, see the corresponding sections below. ### 1. Add your domain name You can add your domain name in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to make changes to. 3. In the top-right corner of the screen, click the **+ Add domain** button. 4. In the **Choose your domain type** dialogue box, click the **Custom domain** button. This takes you to the **Add custom domain** page. 5. In the **Domain name** field, enter your desired domain name. This must include both a root domain and a subdomain. ```https title="Example: Domain name" app.mycompany.com ``` 6. Under the **Choose your certificate type** section, select **Use self-managed certificate**. 7. Click the **Continue** button. You are then taken to the overview page for your new domain. ### 2. DNS setup Before you can use the domain, you must configure the CNAME record with your DNS provider and then validate the DNS changes. To do this: 1. From the **Domain overview** page, see the **DNS setup** section. :::tip Where can I find this? To find the **Domain overview** page: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. For the domain that you want to configure, click the three dots under the **Actions** column. ::: 2. Under **Configure DNS** (step **1** in **DNS setup**), you can see both CNAME records that you need to configure with your DNS provider. Use the copy button beside the CNAME record to copy the value. 3. Go to your host domain provider's portal and paste the CNAME record in your domain's settings. You need to repeat this process so that both records are added. 4. Under **Validate DNS** (step **2** in **DNS setup**), click the **Validate DNS** button to validate your domain. :::note Note It can take some time for DNS updates to become available. ::: ### 3. Certificate setup Before you can purchase an SSL/TLS certificate, you need to generate a Certificate Signing Request (CSR) in the Signicat Dashboard. This contains relevant information about your business that the Certificate Authority (CA) needs to verify your business identity. You then need to share this CSR file with the Certificate Authority (CA) when purchasing the certificate. Once received, you need to upload the certificate in the Signicat Dashboard. To do this: 1. From the **Domain overview** page, see the **Certificate setup** section. :::tip Where can I find this? To find the **Domain overview** page: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. For the domain that you want to configure, click the three dots under the **Actions** column. ::: 2. Under **Create a Certificate Signing Request (CSR)** (step **1** in **Certificate setup**), click the **Generate CSR** button to open the **Generate CSR** dialogue box. 3. Fill in the fields in the form: :::CustomTable | **Field name** | **Description** | **Example** | | :-- | :-- | :-- | | Common name (CN) | The [fully qualified domain name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to secure for your integration. | login.example.com | | Organisation name (O) | Registered legal name of your organisation. | Example Org | | Subject alternative name (SAN) | Optional. Comma-separated list of additional domains. | | | Serial number (SN) | A number that uniquely identifies the certificate and is issued by the certification authority. | | | Locality (L) | Town, city, village name. | Amsterdam | | State or province (ST) | Province, region, county or state. | Noord-Holland | | Country (C) | The [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) where your organisation is registered. | NL | ::: 4. To create and download the CSR, click the **Create** button, then click the **Download now** button. ```bash title="Example: CSR" -----BEGIN CERTIFICATE REQUEST----- ...Base64-encoded string... -----END CERTIFICATE REQUEST----- ``` :::tip Forgot to download the CSR? You can also download the CSR at any time from the **Domain overview** page. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. For the domain that you want to configure, click the three dots under the **Actions** column. 3. Under the **Create a Certificate Signing Request (CSR)** step in the **Certificate setup** section, click the **Download CSR** button beside the CSR that you want to download. ::: 5. Purchase a SSL/TLS certificate from a Certificate Authority (CA), using the CSR that you created in the previous step. :::note Certificate types The type of certificate that you need to purchase depends on requirements of the product that you are integrating with; it can be any combination of the following certificate types: - Domain Validation (DV) - Organization Validation (OV) - Extended Validation (EV) ::: 6. Under **Upload certificate** (step **2** in **Certificate setup**), click the **Upload certificate** button. 7. Locate the file in your file system, then click the **Open** button to upload it. :::tip Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Signicat-managed certificate When you choose a **custom domain** that uses a **Signicat-managed certificate**, Signicat handles the following aspects: - Creation (using [Let's Encrypt](https://letsencrypt.org/)) - Installation - Renewal :::note Note The generated certificates are securely stored on Signicat servers and renewed automatically. ::: ## How to set up a custom domain (Signicat-managed certificate) To add a custom domain using a Signicat-managed certificate, you need to complete the following steps: 1. Add your domain name in the Signicat Dashboard. 2. Configure the CNAME record with your DNS provider, so that traffic targeting your custom domain is forwarded to our servers. To learn how to complete each step, see the corresponding sections below. ### 1. Add your domain name You can add your domain name in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to make changes to. 3. In the top-right corner of the screen, click the **+ Add domain** button. 4. In the **Choose your domain type** dialogue box, click the **Custom domain** button. This takes you to the **Add custom domain** page. 5. In the **Domain name** field, enter your desired domain name. This must include both a root domain and a subdomain. ```https title="Example: Domain name" app.mycompany.com ``` 6. Under the **Choose your certificate type** section, select **Use Signicat-managed certificate**. 7. Click the **Continue** button. You are then taken to the overview page for your new domain. ### 2. DNS setup Before you can use the domain, you must configure the CNAME record with your DNS provider and then validate the DNS changes. To do this: 1. From the **Domain overview** page, see the **DNS setup** section. :::tip Where can I find this? To find the **Domain overview** page: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. For the domain that you want to configure, click the three dots under the **Actions** column. ::: 2. Under **Configure DNS** (step **1** in **DNS setup**), you can see both CNAME records that you need to configure with your DNS provider. Use the copy button beside the CNAME record to copy the value. 3. Go to your host domain provider's portal and paste the CNAME record in your domain's settings. You need to repeat this process so that both records are added. 4. Under **Validate DNS** (step **2** in **DNS setup**), click the **Validate DNS** button to validate your domain. :::note Note It can take some time for DNS updates to become available. ::: 5. Following approval, [Let's Encrypt](https://letsencrypt.org/) reviews your DNS record using challenges, as defined by the ACME standard. If it matches your configuration, Signicat gets approval to request a certificate for your custom domain. 6. Following approval, Signicat requests and installs a certificate for your custom domain. :::tip Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Switch certificate type If you already have a domain but wish to change the type of certificate that it uses, then you can do this without downtime by following one of the procedures described below: ## Switch to a self-managed certificate 1. Add a new domain to your account using the steps shown on the custom domain [Self-managed certificate](/docs/dashboard/organisation-management/domains/custom/self-managed-certificate.mdx) page. :::tip Tip You can add a domain with the same host as an existing domain when you are changing the certificate type. ::: 2. Update your DNS records to match the required DNS records of the new domain. 3. Wait for the Signicat Dashboard to show your new domain as **Active** and the old domain as **Invalid DNS**. 4. The switch is now complete. You can clean up by deleting the old domain. ## Switch to a Signicat-managed certificate 1. Add a new domain to your account using the steps shown on the custom domain [Signicat-managed certificate](/docs/dashboard/organisation-management/domains/custom/signicat-managed-certificate.mdx) page. :::tip Tip You can add a domain with the same host as an existing domain when you are changing the certificate type. ::: 2. Configure the `_acme-challenge.` DNS record as shown in the Signicat Dashboard. :::warning Important Do not update your other DNS record yet. ::: 3. Once the `_acme-challenge` DNS record is configured, refresh the page in the Signicat Dashboard until it shows that the **TLS status** is **Ready**. This may take up to 15 minutes. 4. Update your other DNS record to match the required value shown in the Signicat Dashboard. 5. Wait for the Signicat Dashboard to show your new domain as **Active** and the old domain as **Invalid DNS**. 6. The switch is now complete. You can clean up by deleting the old domain. --- ## Domains A domain is a pointer to the Signicat operational environment that determines the URL at which Signicat products and metadata are available. Domains affect all frontend flows and locations of user interfaces where your end-users experience your services. This allows you to unify the user experience of your service with your company's brand, across Signicat products. On this page, you can find information about what kind of domains are supported and how you can use your own domain name (also known as a CNAME or vanity URL). :::warning Important - For all backend communication with Signicat APIs, you must send requests to `api.signicat.com`. Signicat APIs are always hosted under Signicat domains. - For OIDC and SAML, you must update your application's code to use the domain that you create. ::: :::info Try it in the Signicat Dashboard To manage your domains in the Signicat Dashboard, go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). ::: ## Domain type When you add a domain to your account, you can choose between a **Standard domain** or a **Custom domain** as described in the table below. :::tip Some products require a custom domain Certain products require a custom domain for integration and security purposes. To learn about if this is required, you can refer to the relevant product documentation. ::: :::CustomTable{tableName="Overview of domain types" columnWidths="25% 50% 25%"} | **Domain type** | **Description** | **Example** | | :-- | :-- | :-- | | Standard domain | Get set up without any changes to your DNS configuration, using a Signicat subdomain address. | `.app.signicat.com` | | Custom domain | The URL visible to your end-users displays your brand only, instead of a Signicat subdomain. **Note**: This means that when an end-user logs in or signs documents, redirects to an external website throughout the process are not noticeable to them. | `..com` | ::: ### Set up a domain To learn how to set up a domain for your account, make a selection using the buttons below: * [**Standard domain**](/docs/dashboard/organisation-management/domains/standard): Learn about standard domains and how to set them up * [**Custom domain**](/docs/dashboard/organisation-management/domains/custom/): Learn about custom domains and how to set them up ## Certificate type When you add a custom domain to your account, you can choose between a **Signicat-managed certificate** or a **Self-managed certificate**. :::info Want to learn more? To learn more, see the [Certificate type](/docs/dashboard/organisation-management/domains/custom/index.mdx#certificate-type) section on the **Custom domains** page. ::: ## Certificate status To learn what the different certificate statuses mean that you may encounter in the Signicat Dashboard, see the table below: :::CustomTable{tableName="Overview of certificate statuses" columnWidths="25% 50% 25%"} | **Certificate status** | **Description** | **Domain type** | | :-- | :-- | :-- | | Active | The certificate is active. | All types | | Pending DNS validation | The DNS has not been validated. To validate it, you need to click the **Validate DNS** button on the **Domain overview** page in the Signicat Dashboard. **Note**: Once validated, the certificate is automatically provided. | Custom domain with Signicat-managed certificate | | Missing | The certificate is missing for your custom domain. To add it, you need to upload it on the **Domain overview** page in the Signicat Dashboard. | Custom domain with self-managed certificate | | Expired | The certificate has expired for your custom domain. To renew it, you need to upload a renewed one on the **Domain overview** page in the Signicat Dashboard. | Custom domain with self-managed certificate | | Expires in `X` days | The certificate will expire in the specified number of days. To renew it, you need to upload a renewed one on the **Domain overview** page in the Signicat Dashboard. **Note**: This amount is always less than 30 days. | Custom domain with self-managed certificate | ::: ## DNS status To learn what the different DNS statuses mean that you may encounter in the Signicat Dashboard, see the table below: :::CustomTable{tableName="Overview of DNS statuses" columnWidths="25% 50% 25%"} | **DNS status** | **Description** | **Domain type** | | :-- | :-- | :-- | | Ready | The DNS has been configured and validated. This means that it is ready to use. | All types | | Not configured | The DNS has not been configured. | Custom domains | | Not validated | The DNS has been configured, but it has not been validated. To validate it, you need to click the **Validate DNS** button on the **Domain overview** page in the Signicat Dashboard. | Custom domains | ::: --- ## Standard domain A standard Signicat domain allows you to create your own label/subdomain under a Signicat domain. The certificates for standard Signicat domains are created using [Let's Encrypt](https://letsencrypt.org/). ```https title="Example: Standard domain" .app.signicat.com ``` ## What does it look like? The address of a standard Signicat domain varies depending on whether you are creating it for a sandbox account or a production account, as shown in the table below: :::CustomTable{tableName="Standard domain variations" columnWidths="30% 70%"} | Account type | Subdomain | | :-- | :-- | | Sandbox account | `.sandbox.signicat.com` | | Production account | `.app.signicat.com` | ::: ## How to set up a standard domain You can set up a standard Signicat domain for your account in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to make changes to. 3. In the top-right corner of the screen, click the **+ Add domain** button. 4. In the **Choose your domain type** dialogue box, click the **Standard domain** button. This takes you to the **Add standard domain** page. 5. In the **Domain name** field, enter your desired domain name, then click the **Add domain** button. 6. Optionally, you can set this as your default domain by clicking the **Set as default** button. :::tip Update your code and configuration Remember to update your application's code and configuration to point to the standard domain address that you have created. ::: --- ## Organisation management The Signicat Dashboard lets you structure your resources into organisations and accounts. We offer tools for configuring and organising these resources and their domains. To learn how to do this, see the guides below: * [**Organisations**](/docs/dashboard/organisation-management/organisations): Learn how to add, manage and delete organisations * [**Accounts**](/docs/dashboard/organisation-management/accounts): Learn how to create and delete sandbox and production accounts * [**Domains**](/docs/dashboard/organisation-management/domains/): Learn how to add and manage standard Signicat domains and custom domains * [**Company registration**](/docs/dashboard/organisation-management/company-registration/): Learn how to complete the company registration process --- ## Organisations An organisation is the highest level of hierarchy in the Signicat Dashboard and represents a legal entity with a VAT number. This means that in most cases, you only need to create one which represents your company. An organisation can have several accounts under it, since each account has its own domain, permissions and branding. To learn more about account types, visit the [Accounts](/docs/dashboard/organisation-management/accounts) documentation. :::info Try it in the Signicat Dashboard To manage your organisations in the Signicat Dashboard, go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/). ::: ## Manage your organisation When you register in the Signicat Dashboard, an organisation is automatically created for you. Your first organisation matches the name of your company that you submitted when signing up. ### Register your company details To start using our products you must first register your company details in the Signicat Dashboard. 1. Log in to the [Dashboard](https://dashboard.signicat.com). 2. In the left-hand sidebar menu, select **Organisation**. 3. In the organisation management page, select **Company details**. 4. Select the **Country** where your company is registered and enter your **Company registration number**. 5. Select **Lookup** to verify the information. {/* TODO: Add info about going live to prod */} ## Create an organisation To create any extra organisation in the Signicat Dashboard, do the following: 1. Log in to the [Dashboard](https://dashboard.signicat.com). 2. Using the dropdown at the top left select **Create organisation**. 3. Enter a name for the new organisation and select **Create**. Done! You can always add more organisations by repeating the steps above. The next step is to create an account that belongs to this organisation. Organisation management screen ## Delete an organisation :::note Before you continue Before deleting an organisation, you must *permanently* delete all the accounts associated to the organisation you want to delete. ::: To delete an organisation, do the following: 1. Log in to the [Dashboard](https://dashboard.signicat.com). 2. In the top navigation bar, use the dropdown menu next to view your organisations. Select **Manage** to view your organisation settings. :::tip Show all If your organisation is not listed in the dropdown menu, toggle **Show all** to display all organisations. ::: 3. In the Organisation management page, select **Delete** to delete your organisation. :::warning Deleting an organisation When you delete an organisation, the following happens: - User memberships to the organisation are removed. - User profiles stay active. - Accounts, domains, credentials and resources under the organisation are permanently deleted. Deleting an organisation is a permanent operation that cannot be undone. ::: ## Next steps To start implementing solutions within your organisation, you must first add at least one account. * [**Accounts**](/docs/dashboard/organisation-management/accounts): Learn how to create and delete sandbox and production accounts --- ## Audit logs The Signicat **Audit logs** service allows you to query, view and filter audit log events. :::info Try it in the Signicat Dashboard To access the audit logs service, go to **Signicat Dashboard** > **Settings** > [**Audit logs**](https://dashboard.signicat.com/audit). ::: ## What are audit logs? Audit logs provide you with documented evidence of the sequence of activities that have affected a system, from a security and quality perspective. Activities are represented as events, and are shown for a selected account. ## Change the account When viewing audit logs in the Signicat Dashboard, only the events for a selected account are shown. To change which account you are viewing audit logs for: 1. In the top navigation bar, expand the dropdown menu next to your organisation name. 2. Select the account that you want to view audit logs for. ## Show/hide columns By default, there are five columns of data displayed for each event in the audit logs. To modify which columns are shown in this table: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click the **Columns** button. 2. Tick the boxes corresponding to the information that you would like to see as a column. 3. Click **Apply**. :::tip Reset to default To reset the look of the audit logs table to default: 1. Click the **Columns** button. 2. Click the **Default** button. ::: ## See event details To see more details about a particular event: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click on any event in the table. 2. You are taken to a new page with event details. - Under the **Summary** heading, there is key information about the audit log. You can add information as a filter from this view by clicking the corresponding filter button. - Under the **Log data** heading, there is the event data in JSON format. ## Filter events By default, all audit logs for your account are shown. You can apply filters to narrow down the events shown. ### Apply date range filter To view events for a particular date range using the date filter: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, expand the date dropdown menu to the top right of the table. By default, this is set to **Last 30 days**. 2. Set a date filter using either: - The search field. - One of the suggested ranges. - The **Custom date** option. ### Apply custom event filters To apply custom event filters using a range of different data parameters: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click the **Filters** button. 2. Tick the boxes for the filters that you would like to apply. - Once you tick a box, you need to complete your selection with the required information presented in the user interface. - Some filters are multi-select, whereas some require text input. 3. To save your changes, click the **Apply** button. ### Apply filters using previous events To filter events based on a data parameter from a previous event: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click on any event in the table. 2. On the event details page, under the **Summary heading**, locate the filter that you want to apply. 3. Click the filter button to the right-hand side of that filter name. ### Apply filters from the audit log table For some columns in the audit log overview table such as **Trace**, the filter tool is readily available from the event list. To apply the filter, click the filter button in the applicable column. ### Share the current filters To share the currently applied filters with others such as your colleagues: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, ensure you have applied all desired filters. 2. Copy the URL from your browser, and share this with the intended person. ### Clear the current filters To clear all currently applied filters from the audit logs: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click the **Filters** button. 2. Click the **Clear** button. ## Export data To export the audit logs to a CSV file: 1. From the [Audit logs](https://dashboard.signicat.com/audit) overview, click the **Export** button. 2. A CSV file containing all events that match the filters you have currently applied is downloaded. ## API integration It is also possible for you to view your audit logs using our API. To learn about how to do this, see our **Signicat Audit** API reference documentation. It contains information about available endpoints and properties, in addition to sample requests and responses. * [**Signicat Audit API**](/apis/audit-logs/): Query, view and filter activities in the audit logs --- ## Events and webhooks The Signicat **Events** service lets you create and manage subscriptions to events published by Signicat services. :::info Try it in the Signicat Dashboard To access the events service, go to **Signicat Dashboard** > **Settings** > [**Events**](https://dashboard.signicat.com/events). ::: ## What are events? Events are our way of letting you know when something happens in one of our services. For example, when a document is signed, or if a change is made to your account, then we create an event. Once you subscribe to an event, you automatically receive information about this event into your system. We support delivering events using: - Webhooks - Microsoft Azure Service Bus - Google Pub/Sub - Signicat Mint ### Example use case When a document is signed, your system automatically downloads the signed document. With an event subscription, you do not need to poll our APIs to determine when the documents are ready for download. ## What does an event look like? An event contains nine fields, as illustrated in the table below. Events follow the same structure across all Signicat services, with the exception of the event data (`eventData`) field. This field is given as a JSON object and varies depending on the type of event that is sent. :::CustomTable{columnWidths="25% 50% 25%"} | **Field name** | **Description** | **Type** | | :-- | :-- | :-- | | `id` | The ID of the event. | String | | `timestamp` | The timestamp when the event was created. | ISO 8601 date string | | `sender` | The service which is sending the event. | String | | `eventName` | The name of the event. | String | | `eventData` | The event data. You can see the structure of this for each event type in the Signicat Dashboard. | JSON | | `accountId` | The account ID which the event is sent in the context of. | String | | `organizationId` | The organisation ID which the event is sent in the context of. **Note**: This can be null. | String | | `expiresAt` | The timestamp when the event expires. **Note**: There are no more retries after this timestamp. | ISO 8601 date string | | `tags` | Optional tags that can be included in the event. **Note**: You add tags by setting them in the request to the service publishing the events. | String array | ::: ```json title="Example: Event when a sign order is completed" { "id": "82fa52a9bc7549438b8c6aee71569fa7", "timestamp": "2023-11-13T11:38:10.7302363Z", "sender": "signature-api", "eventName": "order.completed", "eventData": //Json object, "accountId": "a-spge-IL9J9flqic18sh4TsUAo", "organizationId": null, "expiresAt": "2023-11-13T11:38:40.7302345Z", "tags": [ "mock" ] } ``` ## Subscriptions From the [**Subscriptions**](https://dashboard.signicat.com/events/subscriptions) page, you can: - Create new subscriptions - Manage existing subscriptions - Test your events ### Subscription types We support a variety of subscription types that you can use for event delivery. To learn more, see the sections below. #### Webhooks You can subscribe to certain events on your Signicat account by sending a payload to the webhook's configured URL, if you have a public endpoint that we can reach. To do this, see [Set up webhook](https://dashboard.signicat.com/events/subscriptions/setup/webhook) in the Signicat Dashboard. The URL must respond with a HTTP status code of 200-299 within 15 seconds, otherwise the webhook delivery is considered failed and may be retried. For further details, see the [error handling](#error-handling) section. ##### Add a secret token We recommend that you add a secret token to your webhook when creating the subscription. To do this: 1. On the [Set up webhook](https://dashboard.signicat.com/events/subscriptions/setup/webhook) page, tick the box marked **Secret**. A secret token is then automatically generated for you. 2. Copy the secret token. You can then use it to validate that the event payload is coming from Signicat. ##### Validate payloads Using your secret token, we create a HMAC-SHA256 signature of the request body. All requests include a `X-Signicat-Signature` header containing this signature, which you then can use to validate the integrity of the payload and its origin. To validate the request, compute the HMAC digest using your secret token as the signing key and ensure that it matches the signature from the header. ```js title="Example: How to generate signature with Node.js" const crypto = require("crypto"); const secret = "your-secret-token"; // It is important to use raw request body and not deserialize it. Any added whitespace or ordering of properties will result in an invalid hash. const payload = '{"message":"Hello, world"}'; const hmac = crypto.createHmac("sha256", secret); const signature = hmac.update(payload).digest("hex").toUpperCase(); console.log(signature); // => DEF564B8DF06AE55C788493CB414068B2CF017385D96ECB39AA3E844FDBBCDEA ``` #### Azure Service Bus You can subscribe to certain events on your Signicat account to push events to your Azure Service Bus queue. To do this, see [Set up Azure Service Bus](https://dashboard.signicat.com/events/subscriptions/setup/azureservicebus) in the Signicat Dashboard. #### Google Pub/Sub You can subscribe to certain events on your Signicat account to push events to your Google Pub/Sub topic. To do this, see [Set up Google Pub/Sub](https://dashboard.signicat.com/events/subscriptions/setup/googlepubsub) in the Signicat Dashboard. #### Signicat Mint You can subscribe to certain events on your Signicat account to trigger a Mint flow. To do this, see [Set up Mint](https://dashboard.signicat.com/events/subscriptions/setup/mint) in the Signicat Dashboard. ### Add a subscription 1. From the [**Events**](https://dashboard.signicat.com/events) overview, click the **Add subscription** button. 2. Select a subscription type from the list of connections. :::info Want to learn more? To learn more about specific subscription types, see the [Subscription types](#subscription-types) section. ::: 3. Complete the required information specific to that connection type. :::tip How do tags work? Optionally, you can add tags in the **Tag filter** field. This means that we then only forward events that include the specified tags. - The event has to include all of the specified tags in the tag filter in order for it to be forwarded. - If you end the tag with an asterisk, it picks up all events that start with that tag. For example, the tag `test-*` picks up events that start with `test-tag` or `test-event`. ::: 4. Click the **Add** button to create the subscription. ### Manage a subscription To make changes to existing subscriptions that you have set up: 1. From the [**Subscriptions**](https://dashboard.signicat.com/events/subscriptions) overview, click on the subscription that you want to make changes to. 2. On the subscription details page, make your desired changes. 3. To save your changes, click the **Update** button. ### Test your events Our event testing feature makes it possible to test certain events from the Signicat Dashboard. This means that: - When you are integrating, you can create a mock event instead of triggering the actual event. - You can test your subscriptions and event code handling. To use this feature: 1. From the [**Subscriptions**](https://dashboard.signicat.com/events/subscriptions) overview, click the **Test events** button. 2. Select a subscription from the first dropdown menu. 3. Select an event type from the second dropdown menu. 4. Click **Send**. :::note Success! You have now created a mock event. You can view the request body that has been produced for this mock event, so that you can see how it looks before you test. ::: ## Events From the [**Events**](https://dashboard.signicat.com/events) page, you can: - View a list of your event deliveries from the events that you have subscribed to. - View the details of a particular event by clicking on it. Here, you can find the request and response body for the event. ### Event types The list of event types that we support is constantly evolving. You can see the full list of supported events available when you set up a new subscription. To do this: 1. From the [**Events**](https://dashboard.signicat.com/events/events) overview, click the **Add subscription** button. 2. Choose the subscription type that you want to set up. 3. Click the **Selected events** radio button under the **Listen to** section. #### Preview the JSON payload You can preview what the JSON payload looks like for each event when you set up a new subscription. To do this: 1. When seeing the full list of events as described above, click the **Preview** button next to the event that you would like to preview. 2. The JSON payload appears on the right-hand side. ## Error handling An event delivery is considered failed if we are unable to deliver the event. This includes network issues, timeouts and HTTP status codes other than `200-299`. - In general, failures caused by network errors are retried, whereas failures caused by misconfiguration are not retried. This means that only HTTP status codes of `429` and `500-599` are retried. - If a webhook responds with the HTTP status code `410 Gone`, then the subscription is disabled and no further events are delivered. - The time between each delivery attempt starts at approximately one second and rapidly increases towards 24 hours, for up to five days. - If a webhook responds with a `Retry-After` header, then the next delivery attempt is not be retried for at least the duration specified in the header. ## API integration It is also possible for you to manage your event subscriptions using our API. To learn about how to do this, see our **Signicat Events Management** API reference documentation. It contains information about available endpoints and properties, in addition to sample requests and responses. * [**Signicat Events Management API**](/apis/events/): Create and manage subscriptions to events published by Signicat services --- ## Settings To learn how to manage advanced settings in the Signicat Dashboard, see the guides below: * [**Audit logs**](/docs/dashboard/settings/audit-logs): Learn how to manage audit log events * [**Events and webhooks**](/docs/dashboard/settings/events): Subscribe to events published by Signicat services --- ## Support The Signicat **Support ticket** service lets you to create and manage support tickets so that you can contact our experts us with any queries. For example, you may require: - Customer support - Invoice support - Onboarding support - Signicat Spain support :::note Note The **Signicat Spain support** option only applies if you were directly notified to use it. ::: ## Accessing the service To access the support ticket service, you need to have signed up to the Signicat Dashboard, as this is where you manage and create tickets: * [**Create ticket**](https://dashboard.signicat.com/contact-us/tickets/new): Create a new support ticket in the Signicat Dashboard * [**Manage tickets**](https://dashboard.signicat.com/contact-us/tickets): View and manage your support tickets in the Signicat Dashboard ### What roles do you need? To help determine what roles you need for accessing the support ticket service, you can reference the table below: :::CustomTable{columnWidths="25% 75%"} | **Required role** | **Description** | | :-- | :-- | | Support Viewer | Has access to view support tickets and comments. | | Support Sensitive Viewer | Has access to view support tickets and comments. This includes sensitive data. | | Support Editor | Has access to create, update and view support tickets and comments. This includes sensitive data. | | Organisation Viewer | Has access to view all resources and configurations for the organisation, except for sensitive fields such as passwords and API secrets. | | Organisation Admin | Has access to: Create, update and delete accounts and configurations. Invite and administer users for the organisation and child accounts. | ::: ### Applying the role Support tickets are defined at either an organisation-level scope or an account-level scope. This means that when you assign a support role such as **Support Viewer**, **Support Sensitive Viewer**, or **Support Editor**, you must apply it at the appropriate scope: :::CustomTable{columnWidths="25% 75%"} | **Scope** | **Description** | | :-- | :-- | | Organisation level | Applying a role at an organisation level grants the user access to tickets for the entire organisation, including all of the corresponding accounts defined under it. | | Account level | Applying a role at an account level limits the user's access to tickets for only that specific account (or accounts). | ::: :::note Note The tickets you see in the Signicat Dashboard depend on the scope that you have selected. To make a change, click your organisation name in the top navigation bar to expand the dropdown menu, then select the organisation or account that you want to view support tickets for. ::: ### Issues logging in? If you need help with an issue that is preventing you from logging into the Signicat Dashboard, then you can submit a request to our support team with the **Access & User Administration** form by clicking on the button below. Our support team will then assist you with resetting your authentication. :::info Who can use this form? You can only use this form for specific administrative requests, such as if you need to reset two-factor authentication (2FA) or if you need to reactivate your user for the Signicat Dashboard. ::: * [**Access & User Administration form**](https://admin.support.signicat.com/hc/en-us/requests/new): Create a new request with the Access & User Administration form ## How to create a support ticket 1. Go to **Signicat Dashboard** > [**Contact Us**](https://dashboard.signicat.com/contact-us/tickets), then click the **+ Create ticket** button. 2. As you have already selected the organisation and account that you are creating a ticket for, the following details will be prefilled automatically: - Organisation ID - Organisation name - Account name - Account ID 3. Using the **Category** dropdown menu, select the type of support ticket that you want to submit. 4. Using the **Product** dropdown menu, select the product which the support ticket relates to. 5. In the **Subject** field, add a descriptive title for your support ticket. 6. In the **Message** field, describe what you would like assistance with. :::warning Sharing sensitive data Do not share any personal identifiable information (PII) in this field. Sensitive information must only be shared as attachments. ::: 7. To upload attachments, click the **Attach** button under the **Upload files** section. - To share sensitive information as an attachment, you must also tick the checkbox **This ticket contains sensitive data**. - Any subsequent attachments submitted for your tickets are considered sensitive by default, to prevent you from accidentally submitting any sensitive information. :::note Maximum file size The sum of all file sizes must not exceed 10 MB. ::: 8. To submit your ticket, click the **Submit** button. ## How to manage your support tickets 1. Go to **Signicat Dashboard** > [**Contact Us**](https://dashboard.signicat.com/contact-us/tickets). Here, you can see a list of all support tickets that you have submitted for the given organisation. 2. Use the relevant dropdown menus, buttons and fields to filter and order your support ticket using the following parameters: - Filter by: - The category of support tickets. - The product that the support tickets relate to. - The status of the support tickets. - The time frame that the tickets were submitted within. - Order by: - The timestamps when the issues were submitted (ascending or descending). - The timestamps when the issues were last updated (ascending or descending). ## How to share your support tickets If you want to share the contents of a support ticket with a colleague, then there are two methods to do this. :::tip Our recommendation We recommended that you use the [watchers functionality](#using-the-watchers-functionality) in the Signicat Dashboard. ::: ### Using the watchers functionality Once created, a ticket can have one or multiple watchers added. :::note Note Adding a watcher is for informative purposes only. It does not imply sending an invitation to the organisation or account, or granting a role for the support ticket service. ::: To add a user as a watcher: 1. Go to **Signicat Dashboard** > [**Contact Us**](https://dashboard.signicat.com/contact-us/tickets). 2. From the tickets overview page, select the ticket that you want to add a watcher to. This takes you to the ticket details page. 3. Click the **Watchers** button, then click the **+ Add Watchers** button. 4. Enter the email address of the person that you want to add as a watcher. 5. To confirm, click the **Add as a watcher** button. Once a user is added as a watcher, they will then receive ticket status updates as they occur by email. The email update contains the updated ticket status, ticket subject, and a link to the ticket in the Signicat Dashboard. :::warning Important You can only view the ticket contents in the Signicat Dashboard if you have access to the organisation or account, and have the necessary role. ::: ### Using a link As an alternative to using the watchers functionality within the Signicat Dashboard, you can also send the ticket as a link by copying it manually and sending it over your preferred messaging/email platform. :::tip Tip The link must contain the complete `scopeId`. To ensure this, you can copy and paste the entire link for the ticket from your web browser's address bar. ::: To see the ticket, the person receiving the link needs to have the necessary access rights in the Signicat Dashboard, at the given scope. ```https title="Example: Link to support ticket" https://dashboard.signicat.com/contact-us/tickets/{ticket-id}?scopeId=a-page-xxxxxxxxxxx ``` --- ## TLS compatibility To meet strict security and compliance standards, all connections to Signicat require [TLS 1.2](https://datatracker.ietf.org/doc/html/rfc5246) or [TLS 1.3](https://datatracker.ietf.org/doc/html/rfc8446.html). ## Supported cipher suites Your client must support at least one of the following strong cipher suites to connect successfully. For TLS 1.2, the negotiated cipher depends on the type of certificate used: ### TLS 1.3 * `TLS_AES_128_GCM_SHA256` * `TLS_AES_256_GCM_SHA384` ### TLS 1.2 * `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` *(EC certificates)* * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` *(RSA certificates)* * `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` *(EC certificates)* * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` *(RSA certificates)* ## Supported elliptic curves For key agreement, the following elliptic curves are supported: * `P-256` * `P-384` ## Troubleshooting connectivity We strongly recommend configuring your clients and integrations to use the latest secure protocols and ciphers to maintain a stable connection to our platform. If your application experiences connectivity issues or handshake failures when connecting to Signicat, verify that your HTTP client or network infrastructure is configured to use at least TLS 1.2 alongside the supported cipher suites and curves listed above. --- ## API overview for Data Verification API # API overview This overview of the API covers key information to help you understand the API, and its endpoints. The Data Verification API returns normalised data from carefully-selected sources, making it easy for you to interpret and use the responses regardless of the source. You can find the full list of endpoints in the [Data Verification API reference](/apis/data-verification/). :::tip Coverage For an overview of all data sources and countries available by endpoint, visit the [Coverage](/docs/data-verification/coverage.mdx) page. ::: ## Endpoints for natural persons ### Account holder The [Account holder endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_VerifyAccountNumber_GET) allows you to verify if a specific bank account exists and if the name of its owner matches the name you provide. Depending on the source, either IBAN or account number can be provided as input. ### Basic information The [Basic endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetBasic_GET) contains basic information about a person like name, address (specifying multiple types of address if registered in the data sources, such as postal, permanent, foreign), date of birth (including place of birth), citizenship (multiple citizenship, if any), and nationality. ### Finance The [Finance endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetFinance_GET) can be used to retrieve financial information about a person. For example, their credit score and information about their income and wealth. ### Identity verification The [Identity verification endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_VerifyAddress_GET) can be used to verify a natural person's identity and address information. The endpoint returns a value (`identified`, `partiallyIdentified`, `notIdentified`) to confirm whether a given person's identity and address attributes provided in the API request match the data found in the registries. Use this endpoint to perform checks for data consistency that include checking the given address and identity attributes, such as the combination of name, surname and residential address, against the available data sources. For example, you can use this endpoint if you already know someone's address and need to perform enhanced due diligence to verify the person and address authenticity. ### Screening The [Screening endpoint](pathname:///apis/data-verification/#tag/Persons/operation/PersonGlobal_Screening_GET) provides information about whether the person in question is: - a PEP (politically exposed person) - on a sanction list - on an adverse media list #### PEP A politically exposed person is someone who has a prominent public function and, thus, presents a higher risk of involvement in, for example, bribery or corruption. Family members or close associates of such people are also considered PEPs. It is important to be aware of the PEP status of one's customers in order to apply any precautions that may be necessary. Signicat covers the following standard PEP lists: - The Acuris C6 global PEP list - PEP Edge (detailed coverage of Nordic PEPs, where [Trapets](https://www.trapets.com/) is the editor) #### Sanction lists Sanction lists are created by one or more countries or public bodies to apply commercial or financial penalties to individuals, groups, or entire countries. For example, the EU has sanctions that involve freezing the funds and economic resources of specific natural persons and organisations. To observe these restrictions properly, it is important to check that your customers are not included in any sanction lists. Signicat covers the following standard sanction lists: - EU Consolidated list of persons, groups, and entities subject to EU financial sanctions. - UN consolidated - OFAC Specially Designated Nationals - HM Treasury - consolidated list of financial sanctions Optionally, local national sanction lists can be enabled on request. ### Search With the [Search endpoint](pathname:///apis/data-verification/#tag/Persons/operation/PersonGlobal_Search_GET), you can search for a person's ID number using several parameters, such as name and date of birth. :::warning Beta This endpoint is in beta. Its functionality is subject to change without prior notice. ::: ## Endpoints for organisations ### Account holder (org) The [Account holder endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_VerifyAccountNumber_GET) allows you to verify if a specific bank account exists and if the name of its owner matches the company name you provide. Depending on the data source, you can make a request with either: - IBAN - Account number The usage of query parameters in this endpoint varies based on the source and country where you want to verify an IBAN or an account number. The following table shows how to use the query parameters: :::CustomTable{columnWidths="25% 75%"} | Parameters | Description | | --------------- | ------------------ | | `accountNumber` | The account number or IBAN number that you want to verify. This is a required parameter. | | `idList` | The company ID, branch ID and VAT number of the organisation, that you want to verify together with the IBAN number. This parameter is specific to **Surepay** data source. Available values per country: Netherlands: `NL_KVK`, `NL_KVK_BRANCH`, `EU_VAT`France: `FR_SIREN`, `FR_SIRET`Italy: `EU_VAT`. For Italy, sending the `EU_VAT` number for IBAN validation is mandatory.UK: `UK_CRN` The `idList` format is: `, ` (e.g `NL_KVK, 012345678`). | | `idType` | The type of `accountNumber` that is being validated. If not specified, `IBAN` is used by default. This is specific to Surepay data source. | | `name` | Name of the organisation to verify. | | `country` | The country code (ISO 3166-1 format) under consideration for IBAN verification. For example, to verify an IBAN from Netherland, then use country code `NL`. This parameter determines the country used in the `idList` parameter. This is a required parameter. | ::: **Example** The following API request example can be used to verify an IBAN together with the name of an organisation (`name`), KVK number (`NL_KVK`), KVK branch number (`NL_KVK`) and VAT number (`EU_VAT`). ```bash https://api.signicat.com/info/lookup/countries/NL/organizations/accountnumber/NL72ABCD1236548754/verify? &name=We care 4 U &idType=IBAN &idList=NL_KVK, 01234565 &idList=NL_KVK_BRANCH, 012345698124 &idList=EU_VAT, NL1245658 ``` **Parameters overview** Example of idList parameter :::tip Add a parameter To verify any additional parameter (together with the IBAN), you must specify the parameters in the _query string_ of the URL in your API request. For example, `https://api.signicat.com/info/lookup/countries/NL/organizations/accountnumber//verify?name=&idType=IBAN&idList=`. ::: ### Basic information (org) The [Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetBasicOrganizationInfo_GET) provides standard information about an organisation like trade name, address, organisation type, legal status, and industry sector. ### Ownership (org) The [Ownership endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetOwnership_GET) provides information about the owners of an organisation. Owners of an organisation can be natural persons or other organisations. ### UBO (org) The [UBO endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetUbo_GET) provides information about the Ultimate Beneficiary Owner (UBO) of an organisation. UBO is a term used to describe the natural person who is the ultimate effective owner of an organisation, even if that person is not a direct owner of that organisation. For example, imagine a case where the company you need more information about is owned by another company, which is owned by a natural person. This UBO wouldn't appear in the ownership attribute, since they are not a direct owner of the company. Establishing the UBO can be challenging, especially when ownership is distributed over different countries or passes through countries like Liechtenstein or Bermuda. As defined by the [4th EU AML directive](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32015L0849&from=EN), a UBO is any natural person who, directly or indirectly: - holds at least 25% plus one share of the share capital, or - exercises at least 25% of the voting rights, or - is the beneficiary of at least 25% of the legal entity's capital Note that this definition has been simplified and you should review the directive if you want to know more. Also, note that each country may define even lower thresholds, according to which a natural person can be considered a UBO, so it is always important to review the domestic laws applicable. #### Key terms (org) This section summarises some terms related to UBO that are used in the Data Verification API. - **Direct ownership**: This is the simplest ownership model. A person or entity is considered a direct owner of an organisation if they do not own it through another entity. - **Indirect ownership**: A person or entity is considered an indirect owner of an organisation if they own an entity that, in turn, owns the organisation we are interested in. For instance, if John owns (or partially owns) Company A, and Company A is a direct owner of Company Z, that makes John an indirect owner of Company Z as well. Indirect ownership can have one or multiple paths: extending our example above, if John also owns a second company, Company B, and this entity is a part-owner of Company Z, that makes John the indirect owner of Company Z through two different paths. This will also affect how the indirect ownership percentage is calculated. - **Integrated ownership**: The sum of direct and indirect ownership a person or other entity has in a specific company (source: [T-rank](https://docs.trank.no/white_papers/t-rank_white_paper_indirect.pdf)) - **Voting rights**: Rights granted to a person or entity in connection with how many shares they own in an organisation. There typically is a direct correlation between shares owned and voting rights: if John owns 20% of the shares of Company A, his vote is worth 20%. However, note that voting rights can be restricted or expanded by using different types of shares (_share classes_). For example, one could define share classes which only give the right to receive financial returns on the investment, but without the right to vote at the shareholders' assembly. - **Voting power**: A part-owner of an organisation can have more or less voting power based on how much they can impact a vote in different scenarios. Voting power is not directly correlated to shares owned (when those shares give the right to vote at the shareholders' assembly). For example, consider an organisation with three shareholders, two of which hold 49.5% of the shares each, with the third one, Natalie, holding only 1% of the shares. In any voting scenario in which the other two shareholders don't agree, Natalie will always sway the vote, which gives her a voting power of 50%. #### Related links (org) The following links might be useful if you want to learn more about how different ownership models are calculated: - [Exploring integrated ownership: direct, indirect and multiple-path](https://www.bvdinfo.com/en-gb/blog/compliance-and-financial-crime/exploring-integrated-ownership-direct-indirect-and-multiple-path), by Bureau Van Dijk. - [Integrated Ownership Calculation](https://docs.trank.no/white_papers/t-rank_white_paper_indirect.pdf) (pdf), by T-rank. ### Roles (org) The [Roles endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET) provides the personal details of natural persons who have a registered role within an organisation, such as board members and daily management. In addition, this step returns information about external third-party service providers, such as accountancy and bookkeeping firms. ### Authorisations (org) The [Authorisations endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetAuthorization_GET) tells you about persons or organisations ("signees") who have been authorised to act on behalf of the organisation on a certain matter ("mandate"). We identify two different types of authorisation: - Signing rights, covering people with authorisation to sign and to act on behalf of the business in **all** matters. - Power of procuration, people with the authorisation to sign and to act on behalf of the business in specific, **limited** matters. For both types of authorisation, we try to generate all possible combinations of required persons to achieve a certain mandate. This makes it easy for you to do automatic checks on mandates. You could for example automatically check the validity of a signed document by checking the signees with the list we provide (for the applicable mandate). If we cannot establish the possible combinations of persons (for a specific mandate), we will inform you about the mandates of individual signees. **Special cases** For Swedish organisations with business type _Aktiebolag_ (limited company), if the company only consists of one board member and one deputy board member - this is the minimum requirement for a limited company - the only board member has the right to sign himself for the company. Visit the [Swedish Companies Registration Office (Bolagsverket)](https://bolagsverket.se/foretag/aktiebolag/startaaktiebolag/firmateckningiaktiebolag.519.html) website for more details. ### Screening (org) The [Screening endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Screening_GET) tells you if the organisation is mentioned on any sanction lists. Sanction lists are created by one or more countries to apply commercial or financial penalties to individuals, groups, or entire countries. For example, the EU has sanctions that involve freezing the funds and economic resources of specific natural persons and organisations. To observe these restrictions properly, it is important to check that your customers are not included in any sanction lists. ### Finance (org) The [Finance endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetFinance_GET) allows you to retrieve some financial information about an organisation. This includes information such as their credit rating and yearly profit/turnover figures. ### Search (org) With the [Search endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Search_GET), you can search for an organisation by name in cases when the organisation number is not available. The response returns all organisations (together with the address details) that match the name sent in the request. ### About the ID parameter in organisation endpoints Most organisation endpoints in the Data Verification API have two required path parameters: - `country` - `id` These parameters serve to narrow down the organisation that you want to obtain information about. There is only one way to use the `country` parameter (by entering an ISO 3166-1 country code), but several in the case of `id`. There are three different types of IDs that can be used to identify an organisation: - `organization`: the ID of the organisation as stated in the relevant national registry. This is the default option. Not always unique. - `tax`: the tax ID of the organisation as stated in the relevant tax registry. For example, EIN in the US. - `external`: the ID assigned to the organisation by the source that provides organisational information. Always unique. You can specify which type of ID you want to use in your request with the `idType` query parameter. In some cases, you can skip this and let the API use the default option (`organization`). You can use the default option if the organisation is registered in a country where organisation numbers are unique, such as Norway or Sweden. In countries where organisation numbers are not unique, like the US or Germany, you could get multiple hits when you try to use the organisation number. If this happens, we suggest using the tax ID or external ID as an alternative. An example of an external ID is the DUNS number (assigned by Dun & Bradstreet) or the BvD ID (assigned by Bureau van Dijk). #### How to look up organisations using a tax or external ID If you can't use an organisational ID, you can find out a company's tax ID or external ID with the Search endpoint of the Data Verification API. Therefore, there are two main steps: 1. Use the [Search endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Search_GET) to find the company you are interested in. Extract the `externalId` or `taxNumber` from the response. 2. Use the extracted ID on any of the other organisation endpoints to find the information you want. What follows is an example of how to find the ultimate beneficial owners of a fictional German company called "Nunstück GmbH". Note that all information used here is fictional. 1. Use the [Search endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Search_GET) to find the company you are interested in. It helps to use several parameters to refine your search. For our example, we enter `Nunstück` as the `name` and `DE` in `countries`. If you know the organisation number, it helps to use it here (in the `id` parameter). Even though it isn't unique, using it together with the name increases the likelihood of getting a single result in the response. 2. Review the API response. If there are several results, identify the company you're interested in based on the `data` of each result. 3. Find Nunstück's `taxNumber` or `externalId` in the `data` array of the response. For this example, we use the external ID. 4. Use the [Ultimate beneficial owners endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetUbo_GET) to find out the information you need. Enter `DE` as the `country`, the external ID obtained in the previous step as the `id`, and `external` as the `idType`. The response will contain information about the ultimate beneficial owners of Nunstück GmbH. The images below show two examples of how to use the `idType` parameter: Example query parameters with source set to bvd and idType set to external Example query parameters with source set to bvd and idType set to tax --- ## Code examples for Data Verification # Code examples This page guides you through the steps to build a simple application to integrate with the Signicat Data Verification API using .NET 8.0. The code examples show how to set up a minimal ASP.NET Core project to fetch basic information about persons and organisations from the API using token-based authentication. Here are the steps that you will follow: 1. Connect to the Data verification API 2. Prepare your development environment 3. Authenticate to the Data Verification API 4. Call the Organisation and Person Basic endpoints with test data 5. Review the API response You can extend the code examples in this guide to cover other scenarios by using the sources documented on the [Data sources](/docs/data-verification/data-sources/) pages. ## Connect to the Data Verification API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set the following permissions for your API client: - **Data Verification for natural persons** to connect to data sources about natural persons. - **Data Verification for organisations** to connect to data sources about organisations. ::: Then, return here and continue with the next steps of this guide. ## Prepare your development environment Before you begin, ensure that you have the following tools installed in your development machine: - [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) You will need the .NET CLI to run this example, read more about it at [https://learn.microsoft.com/en-us/dotnet/core/tools/](https://learn.microsoft.com/en-us/dotnet/core/tools/). ## Clone and configure the project ### Clone the code Clone the repository to your local machine using the following command: ```bash git clone https://github.com/signicat/sample-data-verification ``` Or, download the code compressed in a zip file: * [**Download full code example**](https://github.com/signicat/sample-data-verification/archive/refs/heads/main.zip) The full code example includes all the files you need to run the sample application. :::details Preview application code ```dotnet // Create a new WebApplication var builder = WebApplication.CreateBuilder(args); // Configure in-memory settings for TokenService var inMemorySettings = new List> { new("TokenServiceConfig:GrantType", "client_credentials"), new("TokenServiceConfig:Scope", "signicat-api"), new("TokenServiceConfig:ClientId", ""), new("TokenServiceConfig:ClientSecret", "") }; // Build configuration from in-memory settings var configuration = new ConfigurationBuilder() .AddInMemoryCollection(inMemorySettings) .Build(); // Configure TokenServiceConfig using the built configuration builder.Services.Configure( configuration.GetSection("TokenServiceConfig")); // Configure HttpClient for TokenService builder.Services.AddHttpClient("TokenService", httpclient => { httpclient.BaseAddress = new Uri("https://api.signicat.com/auth/open/"); }); // Add TokenService as a singleton service builder.Services.AddSingleton(); // Configure HttpClient for DataVerificationApiService builder.Services.AddHttpClient("DataVerificationApiService", httpclient => { httpclient.BaseAddress = new Uri("https://api.signicat.com/info/lookup/"); }); // Add DataVerificationApiService as a singleton service builder.Services.AddSingleton(); // Build the application var app = builder.Build(); // Set up a simple root route app.MapGet("/", () => "Signicat Data Verification Sample App."); // Set up routes for person and organization information var person = app.MapGroup("/person"); person.MapGet("/basic/{country}/{source}/{id}", GetPersonBasic); var organization = app.MapGroup("/organization"); organization.MapGet("/basic/{country}/{source}/{id}", GetOrganizationBasic); // Run the application app.Run(); // Handler for getting basic person information static async Task GetPersonBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService) { var response = await dataVerificationApiService.GetPersonBasic(country, source, id); return TypedResults.Ok(response); } // Handler for getting basic organization information static async Task GetOrganizationBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService) { var response = await dataVerificationApiService.GetOrganizationBasic(country, source, id); return TypedResults.Ok(response); } ``` ```dotnet // DataVerificationApiService class to handle API requests for person and organization information public class DataVerificationApiService(IHttpClientFactory httpClientFactory, TokenService tokenService) { // Get basic person information from the API public async Task GetPersonBasic(string country, string source, string id) { return await MakeRequest($"countries/{country}/persons?identityNumber={id}&source={source}"); } // Get basic organization information from the API public async Task GetOrganizationBasic(string country, string source, string id) { return await MakeRequest($"countries/{country}/organizations/{id}?source={source}"); } // Helper method to make an authenticated API request private async Task MakeRequest(string url) { var httpClient = httpClientFactory.CreateClient("DataVerificationApiService"); // Get an authentication token from the TokenService TokenResponse? token; try { token = await tokenService.GetToken(); if (token == null) return "Something went wrong fetching the authentication token"; } catch (Exception ex) { return ex.Message; } // Set the authorization header with the access token httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token.AccessToken); // Make the API request var httpResponseMessage = await httpClient.GetAsync(url); // Handle the API response if (!httpResponseMessage.IsSuccessStatusCode) { if (httpResponseMessage.StatusCode == System.Net.HttpStatusCode.NotFound) return "The entity you tried to look up was not found at the source."; else return httpResponseMessage.StatusCode + ", " + httpResponseMessage.ReasonPhrase; } // Read and return the response content var responseContent = await httpResponseMessage.Content.ReadAsStringAsync(); return responseContent; } } ``` ```dotnet using System.Text.Json.Serialization; // TokenResponse class representing the token response public class TokenResponse { [JsonPropertyName("access_token")] public string? AccessToken { get; set; } } ``` ```dotnet using Microsoft.Extensions.Options; // TokenService class to handle authentication token requests public class TokenService(IHttpClientFactory httpClientFactory, IOptions configuration) { private readonly TokenServiceConfig _configuration = configuration.Value; // Get an authentication token from the token service public async Task GetToken() { var httpClient = httpClientFactory.CreateClient("TokenService"); // Prepare the request content with client credentials var requestContent = new List> { new("grant_type", _configuration.GrantType), new("scope", _configuration.Scope), new("client_id", _configuration.ClientId), new("client_secret", _configuration.ClientSecret) }; // Make the token request var httpResponseMessage = await httpClient.PostAsync("connect/token", new FormUrlEncodedContent(requestContent)); // Handle the token response if (!httpResponseMessage.IsSuccessStatusCode) throw new Exception(httpResponseMessage.StatusCode.ToString()); // Read and deserialize the token response var responseContent = await httpResponseMessage.Content.ReadAsStringAsync(); return System.Text.Json.JsonSerializer.Deserialize(responseContent); } } ``` ```dotnet // TokenServiceConfig class representing configuration properties public class TokenServiceConfig { public string? GrantType { get; set; } public string? Scope { get; set; } public string? ClientId { get; set; } public string? ClientSecret { get; set; } } ``` ::: :::note Limitations of the code example The code used in this sample application is meant to be easy to understand and may not follow best practices. Make sure your code adheres to coding and security standards, when preparing your applications for production. ::: ### Configure the credentials To make requests to the API endpoints, the application first needs to authenticate to the Signicat authorisation server using your API client credentials. Edit the API client credentials, the client ID and the client secret, in the `Program.cs` file. Replace `` and `` with the values of your API Client. ```dotnet {5-6} // Configure settings for TokenService var inMemorySettings = new List> { new("TokenServiceConfig:GrantType", "client_credentials"), new("TokenServiceConfig:Scope", "signicat-api"), new("TokenServiceConfig:ClientId", ""), new("TokenServiceConfig:ClientSecret", "") }; ``` ## Authenticate to the API To make requests to the API, you first need to obtain an access token. To do this, you need to call the `https://api.signicat.com/auth/open/connect/token` address with your client credentials in the request content. Then, the authorisation server provides your application with a token that can be used to interact with the API. The `TokenService` class handles the request to the Signicat API authorisation server, as shown below: ```dotnet // TokenService class to handle authentication token requests public class TokenService { private readonly IHttpClientFactory _httpClientFactory; private readonly TokenServiceConfig _configuration; public TokenService(IHttpClientFactory httpClientFactory, IOptions configuration) { _httpClientFactory = httpClientFactory; _configuration = configuration.Value; } // Get an authentication token from the token service public async Task GetToken() { var httpClient = _httpClientFactory.CreateClient("TokenService"); // Prepare the request content with client credentials var requestContent = new List> { new("grant_type", _configuration.GrantType), new("scope", _configuration.Scope), new("client_id", _configuration.ClientId), new("client_secret", _configuration.ClientSecret) }; // Make the token request var httpResponseMessage = await httpClient.PostAsync("connect/token", new FormUrlEncodedContent(requestContent)); // Handle the token response if (!httpResponseMessage.IsSuccessStatusCode) throw new Exception(httpResponseMessage.StatusCode.ToString()); // Read and deserialize the token response var responseContent = await httpResponseMessage.Content.ReadAsStringAsync(); return System.Text.Json.JsonSerializer.Deserialize(responseContent); } } ``` The Signicat API authorisation server validates your client credentials and returns an access token that grants your application access to the Data Verification API. ### Run the application To run the application locally on your machine: 1. Open a terminal and go to the `src` folder. 2. Enter the `dotnet run` command. :::note Checkpoint Now that you have configured the credentials and run your application, verify that: - Navigating to `http://localhost:7650` in your browser, you can view the "Signicat Data Verification Sample App." text. ::: ## Retrieve data about an organisation When calling the [Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) of the Data Verification API, you can retrieve basic information about an organisation, such as name, address and contact. In the API request, you need to specify: - Organisation ID - Country code - Data source :::warning Data sources Note that specifying a data source is optional when you use the Data Verification API outside the scope of this guide. By default, the API selects the best source available in your portfolio in the Dashboard. Learn more about data sources in the [Data sources](/docs/data-verification/data-sources/) page. ::: ### Build the API request With the sample application running in the background, you can perform an API request using your browser. When you navigate to a specific URL path, the application: - Makes a call to the API - Retrieves the data - Displays the response as a string You can build your URL path using the following URL structure: ```http http://localhost:7650/organization/basic/{country}/{source}/{id} ``` **Example** For example, you can look up information about Signicat in the Brønnøysundregistrene (business registry in Norway) using the [Basic organisation endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) in the background. To do this, use the following values: :::CustomTable{columnWidths="33% 33% 33%"} | Country code | Organisation ID | Data source | | ------------ | --------------- | ----------- | | `no` | `989584022` | `no-brreg` | ::: and build the URL like: ```http http://localhost:7650/organization/basic/no/no-brreg/989584022 ``` :::note Checkpoint Now, verify that: - Navigating to `http://localhost:7650/organization/basic/no/no-brreg/989584022` in your browser you can view the response from the API. ::: ### Advanced code analysis In this section, you can find additional details to help you understand how the application code works. :::details Click to expand The application builds the URL routes with the following code: ```dotnet title="src/Program.cs" ... var organization = app.MapGroup("/organization"); organization.MapGet("/basic/{country}/{source}/{id}", GetOrganizationBasic); ... ``` When you navigate to the organisation URL, the `GetOrganizationBasic` handler is called: ```dotnet title="src/Program.cs" ... // Handler for getting basic organization information static async Task GetOrganizationBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService) { var response = await dataVerificationApiService.GetOrganizationBasic(country, source, id); return TypedResults.Ok(response); } ... ``` This triggers the `DataVerificationApiService` class, which contains the `GetOrganizationBasic` method: ```dotnet title="src/DataVerificationApiService.cs" // DataVerificationApiService class to handle API requests for person and organization information public class DataVerificationApiService(IHttpClientFactory httpClientFactory, TokenService tokenService) { ... // Get basic organization information from the API public async Task GetOrganizationBasic(string country, string source, string id) { return await MakeRequest($"countries/{country}/organizations/{id}?source={source}"); } ... } ``` The method receives the values `country`, `source`, `id` from the URL route and formats them into a request to the Data Verification API [Basic organisation endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo), using the following structure: ```http https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source} ``` The complete cURL request with an access token would look like this: ```sh curl -X GET https://api.signicat.com/info/lookup/countries/no/organizations/989584022?source=no-brreg -H "Accept: application/json" -H "Authorization: Bearer {token}" ``` ::: ## Retrieve data about a person To retrieve basic information about a person, you can use the Data Verification API [Persons Basic endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetBasic_GET). Using the application, you can get this information using the URL route: ``` http://localhost:7650/person/basic/{country}/{source}/{id} ``` Substitute the `{country}`, `{source}`, and `{id}` variables with actual values. **Example** For example, you can use synthetic data provided by Tenor test data for the Norge Folkeregisteret (Norway National Registry): :::CustomTable{columnWidths="33% 33% 33%"} | Country code | Identity number | Data source | | ------------ | --------------- | ----------- | | `no` | `13917099981` | `no-freg` | ::: :::note Checkpoint Now, verify that by navigating to `http://localhost:7650/person/basic/no/no-freg/13917099981` in your browser, you can view the response from the API. ::: ## Next steps Learn more about the Data Verification API to extend your application and integrate with more endpoints: * [**Data Verification API**](/apis/data-verification/): Retrieve information about natural persons or organisations * [**API overview**](/docs/data-verification/api-overview): Learn about the features of the Data Verification API --- ## Person and Organisation Look-Up Coverage for Data Verification # Coverage for Data Verification When performing data enrichment and verification, it is important to understand what kind of information you can retrieve from the registries and what use cases are available in a specific country. The tables on this page show the current coverage details for organisations and natural persons. You can explore data grouped by country and data source. ## Coverage overview The columns in the tables below show what endpoints return data by country. To learn more about the endpoints, visit the [API overview](/docs/data-verification/api-overview.mdx) documentation. ### Natural persons ### Organisations ## Data sources Data sources are mappings to retrieve data from a specific registry or provider. You can learn more about this in the [Data sources](/docs/data-verification/data-sources/) documentation. ### Natural persons ### Organisation --- ## How it works When you make an API call to the Data Verification API, the information you are requesting is retrieved from an official registry (data source), normalised and returned to you according to the format specified in the endpoint you used. You can specify which data source to retrieve data from by passing the name of the source as a query parameter in the request. In this page you can find information about what data sources are available, how to add data sources to your account and how to control which data source to use in an API request. ### Adding data sources in the Dashboard To add, configure and remove data sources in the Signicat Dashboard, navigate to **Products** > [**Data Verification**](https://dashboard.signicat.com/data-verification/list). Here, you can view which data sources are active and which ones need additional configuration before you can start using them. You can also search which data sources are available in your account and filter by attribute or use case. Data sources in the Signicat Dashboard ### Testing with the API In a sandbox account, you get access to a selection of data sources that return test data. You can use these sources to test your application and retrieve test data to validate your flows. When testing the Data Verification API, you may want to submit requests using test data for a specific endpoint, country and data source. This can help you understand how the API works and define validation rules in your application. :::tip Production account To use any data source in a production account, you first need to purchase the data source. You can purchase a new data source in the [Signicat Marketplace](https://dashboard.signicat.com/store-front/marketplace). If you are an existing customer, reach out to your account manager to add new sources to your agreement. ::: ### How to specify a data source in an API request When you make an API call to the Data Verification API, the information you are requesting is retrieved from an official registry (data source), normalised and returned to you according to the format specified in the endpoint. By default, Signicat selects the most appropriate data source based on the product availability in your portfolio to ensure that you receive a correct response. In cases where multiple sources apply to your use case, Signicat chooses the most suitable source. To retrieve data from a specific data source, you must specify the data source as a query parameter in your request. To learn how to specify a data source, see the [Controlling the data source](#controlling-the-data-source) section below. #### Using the default data source The default data source depends on the country and the attribute (endpoint) you query. For example, when requesting basic information about an organisation based in Norway, such as Signicat, you would use the [Organisation > Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) like this: ``` GET https://api.signicat.com/info/lookup/countries/NO/organizations/989584022 ``` where `NO` is the country code and `989584022` is Signicat's `organizationNumber`. In this case, the Data Verification API retrieves the data from Brønnøysundregistrene, the registry of businesses in Norway (data source code is `no-brreg`). This is the default data source because it matches the following conditions: - Registry for organisations - Registry for Norway - Registry for basic information To view what data source was used in a response, inspect the `metadata` field in the API response: ```json {8} { "name": "SIGNICAT AS", ... "organizationNumber": "989584022", ... "metadata": { "sources": [ "no-brreg" ], "urls": [ "https://data.brreg.no/enhetsregisteret/api/enheter/989584022" ], ... } } ``` #### Controlling the data source You can control the data source where to retrieve data from. To do so, you must specify the `source` as a query parameter in the API request. :::warning Important conditions Note that when specifying a data source in your request, the following must be true: - The data source must be active in your account. - The data source must be supported by the attribute/endpoint. - The data source must apply to the country. If your request does not meet any of these conditions, the request fails and you receive an error message in the response. ::: For example, to query basic information about Signicat, as shown in the example above, you could specify a global registry such as Creditsafe in the [Organisation > Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) like this:: ``` GET https://api.signicat.com/info/lookup/countries/NO/organizations/989584022?source=creditsafe ``` The response would look like this: ```json {10} { "name": "SIGNICAT AS", ... "organizationNumber": "989584022", ... ... ... "metadata": { "sources": [ "creditsafe" ], "urls": [ "https://connect.sandbox.creditsafe.com/v1/companies/NO-0-NO00977839?template=basic" ], "lastChanged": "2023-11-09T02:47:49.000Z", ... } } ``` :::tip How data could vary across data sources Responses from different data sources may return different data. This is because each registry provides information in a different way. ::: Visit the [Data sources](/docs/data-verification/data-sources/) to view what data sources are supported by the Data Verification API. --- ## Data sources for Data Verification # Data sources Connect to a broad set of identity data sources for individuals (B2C) and businesses (B2B). Verify name, address, financial data and PEP/sanction list status plus business roles, ownership, authorisations UBOs and more. ## Natural persons ## Organisations --- ## Asiakastieto Finland Asiakastieto is an information provider in Finland. This data source offers data on company ownership, financial aspects and credit ratings. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Finland | | Type of data | Organisation | | Endpoints | Ownership, Roles | | Query parameter | `fi-asiakastieto` | ::: --- ## Bisnode Finland Bisnode Finland provides business and credit information on Finnish companies. This data source helps assess risk and confirm company identity. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Finland | | Type of data | Organisation | | Endpoints | Ultimate beneficial owners, Roles, Authorization | | Query parameter | `fi-bisnode` | ::: --- ## Bisnode Norway Bisnode Norway provides detailed information on companies registered in Norway, including ownership, financial data and credit scores. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Organisation | | Endpoints | Ownership, Ultimate beneficial owners, Roles | | Query parameter | `no-bisnode` | ::: --- ## Bolagsverket Sweden The [Bolagsverket](https://www.bolagsverket.se/) is the official business register in Sweden. It is a centralised and publicly accessible register that contains information about companies, partnerships, sole proprietorships, economic associations and other legal entities operating in Sweden. The register serves as an official record for businesses and is used by entrepreneurs, authorities and the public to verify business details, ensure transparency and facilitate business transactions. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Sweden | | Type of data | Organisation | | Endpoints | Basic, Ultimate beneficial owners, Roles, Authorization | | Query parameter | `se-bolagsverket` | ::: ## Data attributes The Data Verification API provides the following attributes from Bolagsverket: - **Basic** - **Ownership** - **Ultimate Beneficial Owners (UBOs)** - **Roles** - **Authorisation and signatory rights** ## API requests To make an API call to the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) and retrieve data from Bolagsverket, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source}&rawJson=true ``` Note the following parameters in the request: - `id`: The company registration number. - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `se`. - `source`: The data provider or screening source (`se-bolagsverket`). For example, you can look up information about Signicat AB (`id`:`5567615561`) in Sweden (`country`: `se`) by sending this request: ```curl https://api.signicat.com/info/lookup/countries/se/organizations/5567615561?source=se-bolagsverket&rawJson=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the relevant endpoint (for example, the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) used in the sample request). ::: ## Test data You can use the following organisation registration numbers (`id`) for testing the data source: | Company registration number | Company name | |-----------------------------|--------------| | `5567615561` | Signicat AB | | `5560747551` | IKEA of Sweden AB | | `5564377355` | En Bok för Alla Aktiebolag | | `5560117482` | AstraZeneca AB | --- ## Brønnøysundregistrene (BRREG) Norway Brønnøysundregistrene (BRREG) is the Norwegian government agency responsible for managing public registers, including the Norwegian Business Register (Foretaksregisteret), the Register of Legal Entities and other official registries. It is a trusted source for company and organisation data in Norway, providing information on legal entities, ownership, financials and registration details. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Organisation | | Endpoints | Basic, Roles, Authorization, Finance, Search | | Query parameter | `no-brreg` | ::: ## Data attributes The Data Verification API provides the following attributes from BRREG: - **Basic** - **Ownership** - **Roles** - **Authorisation and signatory rights** - **Search** ## API requests To make an API call to the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) and retrieve data from BRREG, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source}&rawJson=true ``` Note the following parameters in the request: - `id`: The company registration number. - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `se,no`. - `source`: The data provider or screening source (`no-brreg`). For example, you can look up information about Signicat AS (`id`:`989584022`) in Norway (`country`: `no`) by sending this request: ```curl https://api.signicat.com/info/lookup/countries/no/organizations/989584022?source=no-brreg&rawJson=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the relevant endpoint (for example, the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) used in the sample request). ::: ### Focus on a branch office Additionally, you may request information about the branch of an organisation by specifying the `idtype=branch`, as a query parameter in the request to the API: ```curl https://api.signicat.com/info/lookup/countries/:country/organizations/:id?source=no-brreg&rawJson=true&idtype=branch ``` ## Test data You can use the following organisation registration numbers (`id`) for testing the data source: | Company registration number | Company name | |-----------------------------|--------------| | `989584022` | Signicat AS | | `977511402` | Bybanen AS | | `959657769` | Bama International AS | | `910747711` | Orkla ASA | | `889531312` | Signicat AS, AVD Stortingsg Oslo (Branch test data) | --- ## BvD (Bureau van Dijk) BvD (Bureau van Dijk) is a global business data provider. This data source offers company structure, ownership, financial data and risk scores. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Basic, Roles, Finance, Search | | Query parameter | `bvd` | ::: --- ## Bureau van Dijk (via T-Rank) Bureau van Dijk (via T-Rank) provides information about company ownership. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Ownership, Ultimate beneficial owners | | Query parameter | `t-rank-bvd` | ::: --- ## Companies House Companies House is the official register of companies in the UK. This data source provides public data on company formation, directors, filings and ownership. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Great Britain | | Type of data | Organisation | | Endpoints | Basic, Ultimate beneficial owners, Roles, Search | | Query parameter | `companies-house` | ::: --- ## CreditSafe CreditSafe is a global business credit report provider. This data source offers scores and summaries to assess business risk. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Basic, Roles, Finance, Search | | Query parameter | `creditsafe` | ::: --- ## CVR (Det Centrale Virksomhedsregister) The [Danish Business Authority (Erhvervsstyrelsen)](https://datacvr.virk.dk/data/?language=en-gb) manages the Danish Central Business Register (CVR), known as Det Centrale Virksomhedsregister. CVR is the official government registry for all businesses in Denmark and Greenland and serves as the authoritative source for company data, including legal entities, ownership, financial data and registration details. This source provides data covering all business types except personally owned companies with an annual turnover lower than 50,000 DKK. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark | | Type of data | Organisation | | Endpoints | Basic, Ownership, Ultimate beneficial owners, Roles, Authorization | | Query parameter | `dk-cvr` | ::: ## Data attributes The Data Verification API provides the following attributes from CVR: - **Basic** (e.g. company name, registration date, legal status, industry, address, organisation type) - **Ownership** (e.g. beneficial owners, founders) - **Ultimate Beneficial Owners (UBOs)** (e.g. ultimate beneficial owners) - **Roles** (e.g. board members, managers, audit firms) - **Authorisation and signatory rights** (e.g. signing combination, where available) ## API requests To make an API call to the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) and retrieve data from CVR, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source}&rawJson=true ``` Note the following parameters in the request: - `id`: The company registration number. - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `dk`. - `source`: The data provider or screening source (`dk-cvr`). For example, you can look up information about Novo Nordisk (`id`:`24256790`) in Denmark (`country`: `dk`) by sending this request: ```curl https://api.signicat.com/info/lookup/countries/dk/organizations/24256790?source=dk-cvr&rawJson=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the relevant endpoint (for example, the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) used in the sample request). ::: ## Test data You can use the following organisation registration numbers (`id`) for testing the data source: | Company registration number | Company name | Notes | |------------|------------------------|---------------------------------| | `36887613` | Legoland ApS | | | `50574911` | IKEA A/S | | | `36074906` | Creditsafe Denmark ApS | | | `43556541` | (r)Evolution ApS | | | `30946537` | DenFriePresse Danmark | No signers identified | | `24256790` | Novo Nordisk | No signers identified | --- ## Data.be KBO Belgium Data.be KBO Belgium provides Belgian company information from the official KBO register. This data source includes ownership, legal status and roles. Learn more at [https://data.be/en](https://data.be/en). ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Belgium | | Type of data | Organisation | | Endpoints | Basic, Roles | | Query parameter | `be-databe` | ::: --- ## Dun & Bradstreet (formerly Bisnode) Dun & Bradstreet (formerly Bisnode) covers company data across multiple countries. This data source is useful for international business checks and credit reports. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark, Finland, Norway, Sweden | | Type of data | Organisation | | Endpoints | Basic, Finance | | Query parameter | `bisnode` | ::: --- ## GLEIF The Global Legal Entity Identifier Foundation manages the LEI system, which links legal entities with unique identifiers worldwide. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Basic, Search | | Query parameter | `gleif` | ::: --- ## Data sources for organisations --- ## KAR (Konto og Adresseringsregister) KAR (Konto og Adresseringsregister) is a Norwegian registry that links businesses and bank accounts. This data source is useful for verifying payment details and preventing fraud. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Organisation | | Endpoints | Account Holder Verification | | Query parameter | `kar` | ::: --- ## KvK API Netherlands The Handelsregister (Trade Register) of the Netherlands provides verified company information used for KYB checks. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Netherlands | | Type of data | Organisation | | Endpoints | Basic, Search | | Query parameter | `kvk` | ::: --- ## KvK HR Netherlands The [Dutch Chamber of Commerce](https://www.kvk.nl/english/) provides current company data, including legal status and directors. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Netherlands | | Type of data | Organisation | | Endpoints | Basic, Ultimate beneficial owners, Roles, Authorization | | Query parameter | `kvk-dataservice` | ::: --- ## OpenCorporates OpenCorporates offers company data from official global public registers. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Search | | Query parameter | `opencorporates` | ::: --- ## OpenRegisters (Kausate) OpenRegisters (Kausate) provides data and documents for organisations in Germany through the German Handelsregister (trade registers). This data source allows you to retrieve real-time current and chronological entity information, shareholder lists, articles of association and structured information on a company. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|-----------------------------------| | Geographical coverage | Germany | | Type of data | Organisation | | Endpoints | Search, Basic, Roles, Documents | | Query parameter | `open-registers` | ::: ## Data attributes The Data Verification API provides the following attributes from OpenRegisters (Kausate): - **Search** - **Basic** - **Roles** - **Documents** The following documents are supported for retrieval: - Basic current entity information (*Aktuelle Daten*): `basic` - Shareholder lists (*Gesellschafterlisten*): `shareholder` - Articles of Association (*Gesellschaftsvertrag/Satzung*): `registration` - Chronological Register Information (*Chronologische Übersicht*): `historical` - Structured Information (*Strukturierte Informationen*): `registerextract` ## API requests The following endpoints are supported through the OpenRegisters (Kausate) integration: :::CustomTable{columnWidths="25% 40% 35%"} | Endpoint | Input parameters | Notes | |-----------|----------------------------------------------------------------|-------------------------------| | Search | `country ( DE )``name``source` | | | Basic | `country ( DE )``Org Number`/`id``source` | Retrieve the company's `externalId` from the `Search` endpoint and provide it as the `id` when calling this endpoint. | | Roles | `country ( DE )``Org Number`/`id``source` | Retrieve the company's `externalId` from the `Search` endpoint and provide it as the `id` when calling this endpoint. | | Documents | `country ( DE )``documentType``id``name``source` | `name` or `id` can be used with this endpoint.Retrieve the company's `externalId` from the `Search` endpoint and provide it as the `id` when calling this endpoint.If no document type is set in the request, the `basic` document type is returned by default. | ::: :::tip Note Because documents are retrieved in real time, requests may occasionally take longer to complete. In such cases, the `orderId` is cached and the document will be available for download on the next attempt. ::: The following is a sample API request to the [Organisation Documents endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Documents_GET): ```curl https://api.signicat.com/info/lookup/organizations/documents?country=DE&documentType=basic&name=volvo &source=open-registers&rawJSON=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the relevant endpoint (for example, the [Organisation Documents endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Documents_GET) used in the sample request). ::: --- ## PRH Finland The Finnish Patent and Registration Office (PRH) and the Finnish Tax Administration are jointly the registrars of the Business and Corporate Information System (YTJ). The types of business registered in PRH can be found at [https://www.prh.fi/en/companiesandorganisations/tilastot/lkm.html](https://www.prh.fi/en/companiesandorganisations/tilastot/lkm.html). ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Finland | | Type of data | Organisation | | Endpoints | Basic, Search | | Query parameter | `fi-prh` | ::: ## Data attributes The Data Verification API provides the following attributes from PRH: - **Basic** - **Search** ## API requests To make an API call to the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) and retrieve data from PRH, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source}&rawJson=true ``` Note the following parameters in the request: - `id`: The company registration number. - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `fi`. - `source`: The data provider or screening source (`fi-prh`). For example, you can look up information about Nokia Networks Oy (`id`:`0101120-3`) in Finland (`country`: `fi`) by sending this request: ```curl https://api.signicat.com/info/lookup/countries/fi/organizations/0101120-3?source=fi-prh&rawJson=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the relevant endpoint (for example, the [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) used in the sample request). ::: ## Test data You can use the following organisation registration numbers (`id`) for testing the data source: | Company registration number | Company name | |-----------------------------|--------------| | `0101120-3` | Nokia Networks Oy | | `0103543-2` | Oy Erik Selin Ab | | `0112308-8` | Handelsbanken Finans Abp | | `0109043-1` | Nordea Kiinteistöomistus Oy | --- ## SurePay SurePay verifies if a business name matches a bank account (IBAN). This helps prevent payment fraud by checking account ownership. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | France, Great Britain, Italy, Netherlands | | Type of data | Organisation | | Endpoints | Account Holder Verification | | Query parameter | `surepay` | ::: --- ## TietoEvry (via T-rank) TietoEvry (via T-rank) provides business data, offering insights into company ownership across the Nordics. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark, Finland, Norway, Sweden | | Type of data | Organisation | | Endpoints | Ownership, Ultimate beneficial owners | | Query parameter | `t-rank-evry` | ::: --- ## Trapets [Trapets](https://www.trapets.com/about-us) helps in meeting compliance requirements, reducing risk and supporting customer onboarding, ongoing due diligence (ODD) and enhanced due diligence (EDD) processes. This data provider features screening for organisations against the PEP, sanction and adverse media lists. Trapets is suitable for both one-time and continuous screening of organisations. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Organisation | | Endpoints | Screening | | Query parameter | `trapets` | ::: ## Data attributes The Data Verification API provides the following attributes from Trapets: - **Screening** ## API requests To make an API call to the [Organisation Screening endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Screening_GET) and retrieve data from Trapets, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{countries}/organizations/screening?name={name}&listType={listType}&source={source} ``` Note the following parameters in the request: - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `se,no`. - `source`: The data provider or screening source (`trapets`). - `name`: The name of the organisation to screen. - `listType`: One or more list categories to check against. Supported values: `pep`, `sanction`, `adverseMedia`. Use commas to separate multiple values. For example, you can screen Extra Företag AB for sanctions by sending this request: ```curl https://api.signicat.com/info/lookup/organizations/screening?name=Extra%20F%C3%B6retag%20AB&listType=sanction&source=trapets ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the [Organisation Screening endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Screening_GET). ::: ## Matching logic Trapets uses two types of name-matching logic when screening: - **Exact match** (also called Regular) - **Phonetic match** (also called Fuzzy) ### Exact match In an exact match, all name parts in the searched name must be equal to name parts in a single list entry. The order of name parts does not matter. :::note Definition "Equal" means character-by-character identical. ::: If a name part appears more than once in the searched name, then it must also appear the same number of times in the list entry. **Examples** - `John John Andersson` *matches* `John John Andersson` - `John Andersson` *matches* `John John Andersson` - `John John Andersson` (search) *does not match* `John Andersson` (list entry) ### Phonetic match Phonetic matching uses fuzzy logic to find names that sound (phonetically) similar, based on the **Metaphone3** algorithm. The system looks for at least one name part in the searched name that phonetically matches a name part in a list entry. Then, it calculates similarity using the **Levenshtein distance** algorithm, which measures how many edits are needed to change one word into another. Each name part's distance is weighted by its length. This means that differences in longer name parts affect the total score more than shorter ones. :::tip Recommended threshold A similarity score (hit rate) between **0.75** and **0.9** is typically recommended for fuzzy matching. ::: ### Score The **score** represents the confidence level of a match, based on Trapets' internal **Hit Rating** system. :::info How it works - The **Hit Rating** is an integer from 1 to 5. - The **score** is calculated by multiplying the **Hit Rating** by 20 to produce a percentage. For example, 5 x 20 = 100%. ::: #### Examples - A **Hit Rating** of 5 (score 100) means a perfect match, typically when a unique identifier, such as social security number (SSN) or company registration number, is used. - If no SSN is provided and the match is based only on name and country, the **Hit Rating** may be lower (1 or 2) and the total score affected (20% or 40%). ### Hit rating Indicates how relevant this list item is to the query. The higher number, the more accurate the match, with 5 being the most accurate. #### Hit rating breakdown **Natural persons** :::CustomTable{tableName="Persons" columnWidths="50% 50%"} | Input | Hit Rating | |------------------------|------------| | SSN | 5 | | Name + Date of birth\* | 4 | | Name + Country | 2 | | Name only | 1 | ::: \* Date of birth can be provided as full date, `YYYY-MM` or just `YYYY`.
**Organisations** :::CustomTable{tableName="Organisations" columnWidths="50% 50%"} | Input | Hit Rating | |------------------------|------------| | Company registration number | 5 | | Name + Country | 2 | | Name only | 1 | ::: ## Screening Logic The KYC screening engine processes input parameters in order of reliability. The flow differs slightly between PEP and sanctions screening. ### PEP screening When screening for politically exposed persons (PEPs), the engine evaluates the input fields in the following order: 1. **Social Security Number (SSN)** - If an SSN is provided and matched, it is considered a definitive match. All other input (name, country, date of birth) is ignored. - If no match is found, the engine excludes list entries with non-matching SSNs. 2. **Date of birth** - If provided, the engine keeps only entries with matching dates of birth or no dates of birth at all. 3. **Country** - If provided, the engine filters out entries from non-matching countries. 4. **Name** - Finally, the engine performs name matching based on either exact or phonetic logic. ### Sanction screening Sanctions screening follows the same process, with one key difference: - **SSNs** are not used, as sanctions lists do not include SSNs. ## Test data :::CustomTable{tableName="Trapets test data"} | List Type | Name | Country | Birth | SSN | List | |----------------|----------------|-----------|---------|--------|----------| | PEP | Sebastian Bengtsson | Sweden | 1980-05-06 | SE198005067031 | PEP_Edge | | PEP | Hamid Forsberg | Sweden | 1965-03-07 | SE196503070895 | PEP_Edge | | PEP | Johan Svensson | Sweden | 1959-03-08 | SE195903082575 | PEP_Edge | | PEP | Katrine Thorstensen | Norway | 1973-11-11 | NO11117319646 | PEP_Edge | | PEP | James Roslund | Sweden | 1957-01-13 | SE195701136771 | PEP_Edge | | PEP (Relative or Close Associate)| Viola Roslund | Sweden | 1956-05-05 | SE195605050342 | PEP_Edge | | PEP (Relative or Close Associate)| Sofia Rosander | Sweden | 1976-09-13 | SE197609138164 | PEP_Edge | | PEP | John Bradshaw | Great Britain | 1978-10-10 | | ACURIS_PEP | | PEP | Alicia Wade | Great Britain | 1943-01-16 | | ACURIS_PEP | | PEP | Sana Dijkhuizen | Netherlands | 1953 | | ACURIS_PEP | | PEP | Dieter Sommer | Germany | 1936-11-18 | | ACURIS_PEP | | PEP/Sanction | Ritva Katariina Rankkala | Finland | | 061282-178E | PEP_Edge/EU_Global | | PEP/Sanction | Birgitta Birgersson | Finland | | 070874-178T | PEP_Edge/EU_Global | | PEP/Sanction | Risto Reippaala | Finland | | 080496-728M | PEP_Edge/EU_Global | | PEP/Sanction | Tomí Tiikeri | Finland | | 121260-123V | PEP_Edge/EU_Global | | PEP/Sanction | Nille Psa Augestad | Norway | 1982-01-18 | NO18018200283 | PEP_Edge/EU_Global | | PEP/Sanction | Lasse-Steffen Goldheim | Norway | 1977-01-18 | NO18017749532 | PEP_Edge/EU_Global/ OFAC | | Sanction | Assar Lovén | Sweden | 1999-01-27 | | EU_Global | | Sanction | Yharnam Hunters OY | Finland | | 3744105-3 | EU_Global, UN_Consolidated | | Sanction | Boletaria | Finland | | 7058505-9 | EU_Global, UN_Consolidated | | Sanction | Lordran Knights | Finland | | 3505875-5 | EU_Global, UN_Consolidated | | Sanction | Tone Olsen | Norway | 1999-09-02 | | OFAC | | Sanction | Henry Montgomery | USA | 1977-07-09 | | OFAC_CS | | Sanction | The Great Bank of Cebala | Tunisia | | | OFAC_CS | ::: --- ## Aristotle Aristotle provides global identity verification. It checks names, addresses and other details using official records from many countries. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Natural persons | | Endpoints | Identity Verification | | Query parameter | `aristotle` | ::: --- ## CPR Denmark CPR (Det Centrale Personregister; Civil Registration System of Denmark) provides personal details of people living in Denmark, including names, addresses and ID numbers. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark | | Type of data | Natural persons | | Endpoints | Address, Basic | | Query parameter | `dk-cpr` | ::: --- ## Dun & Bradstreet (Consumer Intelligence) Dun & Bradstreet (Consumer Intelligence) provides consumer data with support for searching by phone number, first name, last name and date of birth. This source provides updated Nordic customer data that can help to enrich business systems. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark, Finland, Norway, Sweden | | Type of data | Natural persons | | Endpoints | Identity Verification | | Query parameter | `dnb-ci` | ::: --- ## Dun & Bradstreet (formerly Bisnode)(Persons) Dun & Bradstreet (formerly Bisnode) provides financial information in Europe. This data source allows for verification of an individual's identity and creditworthiness. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Denmark, Finland, Norway, Sweden | | Type of data | Natural persons | | Endpoints | Finance, Basic | | Query parameter | `bisnode` | ::: --- ## DVV Finland The Digital and Population Data Services Agency of Finland provides official data about persons and their addresses in Finland. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Finland | | Type of data | Natural persons | | Endpoints | Address, Basic | | Query parameter | `fi-dvv` | ::: --- ## Experian Infoscore (formerly Arvato) Experian Infoscore (formerly Arvato) provides natural person address verification data in Austria and Germany. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Austria, Germany | | Type of data | Natural persons | | Endpoints | Identity Verification | | Query parameter | `arvato` | ::: --- ## Folkeregisteret Norway Norway's National Population Register provides official personal details like names, birth dates and addresses. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Natural persons | | Endpoints | Address, Basic, Search | | Query parameter | `no-freg` | ::: --- ## Data sources for natural persons --- ## Infotorg DSF Infotorg DSF provides personal and address information from a Norwegian database. This data source allows for verification of residency and identity details. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Natural persons | | Endpoints | Address, Basic | | Query parameter | `no-infotorg-dsf` | ::: --- ## KAR (Konto og Adresseringsregister)(Persons) KAR is Norway's account and address register. It provides cross-referenced results about a person's bank accounts and their contact details for secure payments. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Natural persons | | Endpoints | Account Holder Verification | | Query parameter | `kar` | ::: --- ## KRR (Kontakt- og reservasjonsregisteret) KRR (Kontakt- og reservasjonsregisteret) is the national contact register in Norway. It provides contact information such as email addresses and phone numbers for persons. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Norway | | Type of data | Natural persons | | Endpoints | Contact | | Query parameter | `krr` | ::: --- ## LSEG (formerly GDC (Global Data Consortium) LSEG (formerly GDC (Global Data Consortium)) comprises a worldwide network of local data sources. It helps verify identities of natural persons using trusted records from each country. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Natural persons | | Endpoints | Identity Verification | | Query parameter | `gdc` | ::: --- ## Schufa Schufa provides information about a person's credit history and identity. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Natural persons | | Endpoints | Identity Verification | | Query parameter | `schufa` | ::: --- ## SPAR (Statens Personadressregister) SPAR (Statens Personadressregister) is the national address register in Sweden. This data source provides names, ID numbers and current addresses of natural persons. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Sweden | | Type of data | Natural persons | | Endpoints | Address, Basic | | Query parameter | `se-spar` | ::: --- ## SurePay(Persons) [SurePay](https://surepay.nl/en/) is a lookup service for France, Great Britain, Italy and The Netherlands. This data source allows for identity proofing and checks to establish if a bank account (IBAN) belongs to a specific person. This service can be useful in several scenarios. For example, if a company needs to make regular payments to a bank account, they may want to verify the account during onboarding. Integrating with SurePay helps you prevent fraud and mistakes, while improving the user experience. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | France, Great Britain, Italy, Netherlands | | Type of data | Natural persons | | Endpoints | Account Holder Verification | | Query parameter | `surepay` | ::: --- ## Trapets(Persons) [Trapets](https://www.trapets.com/about-us) helps in meeting compliance requirements, reducing risk and supporting customer onboarding, ongoing due diligence (ODD) and enhanced due diligence (EDD) processes. This data provider features screening for persons against PEP, sanction and adverse media lists. Trapets is suitable for both one-time and continuous screening of natural persons. ## Properties :::CustomTable{tableName="Data source specs" columnWidths="50% 50%"} | Property | Value | |-----------------------|--------| | Geographical coverage | Global | | Type of data | Natural persons | | Endpoints | Screening | | Query parameter | `trapets` | ::: ## Data attributes The Data Verification API provides the following attributes from Trapets: - **Screening** ## API requests To make an API call to the [Persons Screening endpoint](pathname:///apis/data-verification/#tag/Persons/operation/PersonGlobal_Screening_GET) and retrieve data from Trapets, build your API request URL like: ```curl https://api.signicat.com/info/lookup/countries/{countries}/persons/screening?name={name}&listType={listType}&source={source} ``` Note the following parameters in the request: - `country`: One or more ISO 3166-1 alpha-2 country codes, separated by commas. For example: `se,no`. - `source`: The data provider or screening source (`trapets`). - `name`: The name of the person to screen. - `listType`: One or more list categories to check against. Supported values: `pep`, `sanction`, `adverseMedia`. Use commas to separate multiple values. For example, you can screen Katrine Thorstensen for PEP, sanctions and adverse media in Sweden by sending this request: ```curl https://api.signicat.com/info/lookup/persons/screening?countries=se%2Cno&name=Katrine%20Thorstensen&source=trapets&listType=pep%2Csanction%2CadverseMedia&rawJson=true ``` :::tip Note The list of parameters shown on this page is not exhaustive. For the full list of query parameters, see the API reference for the [Persons Screening endpoint](pathname:///apis/data-verification/#tag/Persons/operation/PersonGlobal_Screening_GET). ::: ## Matching logic Trapets uses two types of name-matching logic when screening: - **Exact match** (also called Regular) - **Phonetic match** (also called Fuzzy) ### Exact match In an exact match, all name parts in the searched name must be equal to name parts in a single list entry. The order of name parts does not matter. :::note Definition "Equal" means character-by-character identical. ::: If a name part appears more than once in the searched name, then it must also appear the same number of times in the list entry. **Examples** - `John John Andersson` *matches* `John John Andersson` - `John Andersson` *matches* `John John Andersson` - `John John Andersson` (search) *does not match* `John Andersson` (list entry) ### Phonetic match Phonetic matching uses fuzzy logic to find names that sound (phonetically) similar, based on the **Metaphone3** algorithm. The system looks for at least one name part in the searched name that phonetically matches a name part in a list entry. Then, it calculates similarity using the **Levenshtein distance** algorithm, which measures how many edits are needed to change one word into another. Each name part's distance is weighted by its length. This means that differences in longer name parts affect the total score more than shorter ones. :::tip Recommended threshold A similarity score (hit rate) between **0.75** and **0.9** is typically recommended for fuzzy matching. ::: ### Score The **score** represents the confidence level of a match, based on Trapets' internal **Hit Rating** system. :::info How it works - The **Hit Rating** is an integer from 1 to 5. - The **score** is calculated by multiplying the **Hit Rating** by 20 to produce a percentage. For example, 5 x 20 = 100%. ::: #### Examples - A **Hit Rating** of 5 (score 100) means a perfect match, typically when a unique identifier, such as social security number (SSN) or company registration number, is used. - If no SSN is provided and the match is based only on name and country, the **Hit Rating** may be lower (1 or 2) and the total score affected (20% or 40%). ### Hit rating Indicates how relevant this list item is to the query. The higher number, the more accurate the match, with 5 being the most accurate. #### Hit rating breakdown **Natural persons** :::CustomTable{tableName="Persons" columnWidths="50% 50%"} | Input | Hit Rating | |------------------------|------------| | SSN | 5 | | Name + Date of birth\* | 4 | | Name + Country | 2 | | Name only | 1 | ::: \* Date of birth can be provided as full date, `YYYY-MM` or just `YYYY`.
**Organisations** :::CustomTable{tableName="Organisations" columnWidths="50% 50%"} | Input | Hit Rating | |------------------------|------------| | Company registration number | 5 | | Name + Country | 2 | | Name only | 1 | ::: ## Screening Logic The KYC screening engine processes input parameters in order of reliability. The flow differs slightly between PEP and sanctions screening. ### PEP screening When screening for politically exposed persons (PEPs), the engine evaluates the input fields in the following order: 1. **Social Security Number (SSN)** - If an SSN is provided and matched, it is considered a definitive match. All other input (name, country, date of birth) is ignored. - If no match is found, the engine excludes list entries with non-matching SSNs. 2. **Date of birth** - If provided, the engine keeps only entries with matching dates of birth or no dates of birth at all. 3. **Country** - If provided, the engine filters out entries from non-matching countries. 4. **Name** - Finally, the engine performs name matching based on either exact or phonetic logic. ### Sanction screening Sanctions screening follows the same process, with one key difference: - **SSNs** are not used, as sanctions lists do not include SSNs. ## Test data :::CustomTable{tableName="Trapets test data"} | List Type | Name | Country | Birth | SSN | List | |----------------|----------------|-----------|---------|--------|----------| | PEP | Sebastian Bengtsson | Sweden | 1980-05-06 | SE198005067031 | PEP_Edge | | PEP | Hamid Forsberg | Sweden | 1965-03-07 | SE196503070895 | PEP_Edge | | PEP | Johan Svensson | Sweden | 1959-03-08 | SE195903082575 | PEP_Edge | | PEP | Katrine Thorstensen | Norway | 1973-11-11 | NO11117319646 | PEP_Edge | | PEP | James Roslund | Sweden | 1957-01-13 | SE195701136771 | PEP_Edge | | PEP (Relative or Close Associate)| Viola Roslund | Sweden | 1956-05-05 | SE195605050342 | PEP_Edge | | PEP (Relative or Close Associate)| Sofia Rosander | Sweden | 1976-09-13 | SE197609138164 | PEP_Edge | | PEP | John Bradshaw | Great Britain | 1978-10-10 | | ACURIS_PEP | | PEP | Alicia Wade | Great Britain | 1943-01-16 | | ACURIS_PEP | | PEP | Sana Dijkhuizen | Netherlands | 1953 | | ACURIS_PEP | | PEP | Dieter Sommer | Germany | 1936-11-18 | | ACURIS_PEP | | PEP/Sanction | Ritva Katariina Rankkala | Finland | | 061282-178E | PEP_Edge/EU_Global | | PEP/Sanction | Birgitta Birgersson | Finland | | 070874-178T | PEP_Edge/EU_Global | | PEP/Sanction | Risto Reippaala | Finland | | 080496-728M | PEP_Edge/EU_Global | | PEP/Sanction | Tomí Tiikeri | Finland | | 121260-123V | PEP_Edge/EU_Global | | PEP/Sanction | Nille Psa Augestad | Norway | 1982-01-18 | NO18018200283 | PEP_Edge/EU_Global | | PEP/Sanction | Lasse-Steffen Goldheim | Norway | 1977-01-18 | NO18017749532 | PEP_Edge/EU_Global/ OFAC | | Sanction | Assar Lovén | Sweden | 1999-01-27 | | EU_Global | | Sanction | Yharnam Hunters OY | Finland | | 3744105-3 | EU_Global, UN_Consolidated | | Sanction | Boletaria | Finland | | 7058505-9 | EU_Global, UN_Consolidated | | Sanction | Lordran Knights | Finland | | 3505875-5 | EU_Global, UN_Consolidated | | Sanction | Tone Olsen | Norway | 1999-09-02 | | OFAC | | Sanction | Henry Montgomery | USA | 1977-07-09 | | OFAC_CS | | Sanction | The Great Bank of Cebala | Tunisia | | | OFAC_CS | ::: --- ## Data Verification demo # Try the demo Explore the full potential of Data Verification in just a few clicks! You can try out the Data Verification in the [demo page](https://signicat.gitlab.io/info/demo-signicat-person-info/#/), an interface designed to simulate: - API endpoints - Use cases This page contains information to set up and use the Data Verification API demo. ## Connect to the Data Verification API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set the following permissions for your API client: - **Data Verification for natural persons** to connect to data sources about natural persons. - **Data Verification for organisations** to connect to data sources about organisations. ::: ## Get started with the demo To use the demo environment, you need to: 1. On the [demo](https://signicat.gitlab.io/info/demo-signicat-person-info/#/) page, enter your API client credentials. To find your API clients, see the [**API clients**](https://dashboard.signicat.com/api-clients/) page in the Dashboard. 2. Select **Get Token** to authenticate to the Data Verification API. You have now started an authenticated session. Renew your credentials when the session expires. :::tip Ready to go Go ahead and [try out an endpoint](#try-out-an-endpoint) below. ::: ## Try out an endpoint To make your first API request in the demo page: 1. Select **Endpoints** in the top navigation bar. You will view the Organizations, Persons and Sources attributes in the lower half of the page. 2. Select **Organizations** to reveal the available endpoints. 3. Select **Basic** to test the Data Verification API [Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo). 4. Enter organisation test data. For example, to retrieve information about Signicat, use: - Country: `NO` - ID: `989584022` 5. Select **Request** to make the API call and retrieve data about the organisation. Congratulations! You have just made the first request to the Data Verification API. You will now view the response data in a table. You can explore any of the other endpoints available on the demo page. ## Try out a use case The demo page is designed to allow you to explore common use cases by combining multiple features of Data Verification. For example, you can simulate a typical organisation onboarding. To do this in the demo page: 1. Select **Use cases** in the top navigation bar. You will find a selection of use cases in the lower half of the page. 2. Select **Organization Onboarding**. 3. Enter organisation test data. For example, to retrieve information about Signicat, use: - Country: `NO` - ID: `989584022` - Source: optional. 4. Select **Onboard**. In this scenario, we retrieve data from the Basic, Finance and Screening endpoints and organise the results in a table. You can download the result as a PDF. Congratulations! You have just explored one of many scenarios where you can use Data Verification. :::tip Data sources If you want to know more about the data sources supported by the Data Verification API, select the "Search Sources" use case in the demo. To learn more about each data source, go to the [Data sources](/docs/data-verification/data-sources/) documentation. ::: ## Next steps Ready to get started and dive deeper into a code integration? Check out our guides to use the Data Verification API. * [**Quick start guide**](/docs/data-verification/quick-start): Get started with Data Verification * [**Code examples**](/docs/data-verification/code-examples): Dive deep into code examples --- ## Error codes for Data Verification # Error codes When you make a request to the Signicat's Data Verification API and there is an error, you will receive a response with an error message that contains an error code. If you encounter an error and require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. The table below shows how to interpret some of the error codes that you might encounter when using the API. :::tip Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: :::CustomTable{columnWidths="25% 75%"} | Error code | Description | |:-------------- |:------------- | | 0001 | Unauthorised. | | 0002 | Forbidden. | | 1100 | Requested a country that is not implemented. | | 1101 | Requested one or more sources that are currently unavailable. | | 1102 | Request targeted a resource where the requested dataset is not implemented. | | 1103 | Request targeted a resource where the profile is not implemented. | | 1104 | Requested a country that is not implemented by the provided data source. | | 1105 | Requested a profile that is not implemented by the provided data source. | | 1200 | The request targeted a country that does not exist. | | 1201 | Request targeted strict data sources without specifying anyone. | | 1202 | Request targeted one or more data sources that do not exist. | | 1203 | Request targeted a country that is not available. | | 1204 | Invalid request property combination. | | 1205 | Invalid expansion property. | | 1206 | Invalid query. | | 1207 | Invalid date of birth. | | 1208 | Bad request. | | 1209 | Unprocessable entity. | | 1210 | Invalid paging parameters. | | 1220 | Exceeded max iterations while searching for NACE section code, data source is corrupted. | | 1250 | Country not found. | | 1251 | Subdivisions not found. | | 1252 | Countries not found. | | 1300 | Internal communication error. | | 1301 | The source failed to respond within reasonable time. | | 1302 | Internal communication error. | | 1303 | Invalid argument. | | 1304 | Internal communication error. | | 1305 | The requested resource could not be found. | | 1306 | Internal communication error. | | 1307 | Internal communication error. | | 1308 | Source is temporarily exhausted. | | 1309 | Internal communication error. | | 1310 | Internal communication error. | | 1311 | Internal communication error. | | 1312 | Internal communication error. | | 1313 | Internal communication error. | | 1314 | Source is temporarily unavailable. | | 1315 | Internal communication error. | | 1316 | Internal communication error. | | 1500 | Something went wrong. Please contact us for assistance if the problem persists. | | 1601 | Multiple internal communication errors. | | 1700 | Could not find the specified cursor. | | 1701 | Invalid cursor. | ::: --- ## Data Verification Signicat's Data Verification is an identity verification product that allows you to check and verify customer data against national and commercial data sources, for both natural persons and organisations. With the Data Verification API, you can retrieve information about a customer or perform a one-time verification of their data. For example, you can confirm the address and business name of companies, or screen natural persons for politically exposed person (PEP) status. Data Verification helps you comply with Anti Money Laundering (AML) laws by connecting you to trusted data sources through a single point of integration, thus reducing the costs and challenges of integrating with several sources separately. ## Get started * [**Try the demo**](/docs/data-verification/demo): Data Verification in a few clicks * [**Quick start guide**](/docs/data-verification/quick-start): Get started with Data Verification * [**Code examples**](/docs/data-verification/code-examples): Dive deep into code examples ## Use cases Here are some use case examples to better understand how you can use Data Verification for both persons and organisations: - Gather basic identity information for onboarding. - View finance and credit risk rating information. - Identify the ultimate beneficiary owner (UBO) of an organisation. - Retrieve roles and ownership information of an organisation. - Screen a person or an organisation for politically exposed person (PEP), sanction and adverse media status. - Verify the ownership of bank accounts. - Get the signatory rights of an organisation. - Verify identity information provided by the user. - Enrich end-user and organisation data. - Ensure AML/KYC compliance. ### Customer cases You can read about how our customers are using our solutions in the customer cases: * [**Identity fraud**](https://www.signicat.com/customers/surepay): Our customer SurePay has reduced bank and identity fraud * [**Automating AML**](https://www.signicat.com/customers/usbl): Our customer Usbl has automated AML screening of new board members * [**Wealth management**](https://www.signicat.com/customers/zevoy): Our customer Zevoy has improved AML/KYC checks for expense management ## API The Data Verification API returns normalised data from carefully-selected sources, making it easy for you to interpret and use the responses regardless of the data source. * [**Data Verification API**](/apis/data-verification/): Retrieve information about natural persons or organisations * [**API overview**](/docs/data-verification/api-overview): Learn about the features of the Data Verification API * [**Data sources**](/docs/data-verification/data-sources): Understand the data sources ## Additional resources * [**Use cases**](/docs/data-verification/#use-cases): Find answers to your business needs * [**Coverage overview**](/docs/data-verification/coverage): Explore the product offerings across markets ## Support * [**Release notes**](/docs/data-verification/release-notes): View the release notes for Data Verification * [**Error codes**](/docs/data-verification/error-codes): View the error codes for Data Verification If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Quick start guide to Data Verification # Quick start guide Learn how to verify information about natural persons or organisations using the Data Verification API. This quick start guide shows you how to: 1. Connect to the Data Verification API. 2. Send requests to the API endpoints using Postman. ## Connect to the Data Verification API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set the following permissions for your API client: - **Data Verification for natural persons** to connect to data sources about natural persons. - **Data Verification for organisations** to connect to data sources about organisations. ::: ## Get started with Postman This guide provides steps for using [Postman](https://www.postman.com/downloads) to make API calls. We have created a Postman collection that lets you try the Data Verification API. Click the button below to get the collection for Postman. [](https://app.getpostman.com/run-collection/20756027-49d27748-2c66-45a9-928a-579b5c4f3084?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D20756027-49d27748-2c66-45a9-928a-579b5c4f3084%26entityType%3Dcollection%26workspaceId%3D3ea7a3cf-7777-4f42-b4e9-88876cfe660d) For more detailed instructions on how to use the collection, refer to the instructions below. ### Import the collection to Postman 1. Download the [Postman collection](https://elements.getpostman.com/redirect?entityId=20756027-49d27748-2c66-45a9-928a-579b5c4f3084&entityType=collection). 2. Open Postman. 3. Click **File** > **Import** and browse to the collection file to import it. 4. Click the name of the collection and edit the following variables: :::CustomTable{columnWidths="25% 50% 25%" minTableSize="900px"} | Variable | Value | Description | | ----------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | **oauth_url** | `https://api.signicat.com/auth/open/connect/token` | The URL where to authenticate with Signicat APIs. | | **oauth_scope** | `signicat-api` | The API client scope you want to work with. | | **oauth_client_id** | Your Client ID | The Client ID obtained when you created the API Client. | | **oauth_client_secret** | Your Client secret | The Client secret obtained when you created the API Client. | | **baseURL** | `https://api.signicat.com/info/lookup` | The base URL for the Data Verification API. | ::: 5. Click **Save**. Postman collection variables ### Get information You can now retrieve information about a natural person or an organisation. The [API reference](/apis/data-verification/) contains information about each of the available endpoints. For example, to query basic information about an organisation, use the [Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) like this: 1. Go to the Basic endpoint in the Postman collection. 2. Fill in the path parameters. For example, if you want to retrieve information about Signicat, write `NO` in the **country** row and `989584022` in the **organizationNumber** row. 3. Optional. Fill in the query parameters to extend functionality. For example, you can set `rawJson` to `true` if you want to see the raw JSON output of the response. 4. Click **Send**. For example, the request might look like this: ```curl GET https://api.signicat.com/info/lookup/countries/NO/organizations/989584022 ``` You will receive a response with the data you requested. For example: ```json { "name": "SIGNICAT AS", "names": [ { "name": "SIGNICAT AS", "type": "registered", "start": null, "end": null } ], "organizationNumber": "989584022", "country": { "alpha2": "NO", "alpha3": "NOR", "numeric": "578" }, "businessAddress": null, "addresses": null, "organizationType": { "name": "Aksjeselskap", "code": "AS", "url": "https://data.brreg.no/enhetsregisteret/api/organisasjonsformer" }, "legalStatus": "active", "employees": 132, "industries": [ { "code": "58.29", "description": "Other software publishing", "section": "J", "level": 4 } ], "contact": null, "metadata": { "sources": ["no-brreg"], "urls": ["https://data.brreg.no/enhetsregisteret/api/enheter/989584022"], "lastChanged": null, "rawJson": null } } ``` Note that some data is omitted for brevity. You can find a more elaborate example in the [API reference](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo). ## Data sources If you want to know more about the data sources supported by the Data Verification API, you can get a list by using the [Sources endpoints](pathname:///apis/data-verification/#tag/Sources). To view all the sources available for the organisation endpoints, use the Sources endpoint in the Organizations folder of the Postman collection. ``` GET https://api.signicat.com/info/lookup/sources/organization ``` To view all the sources available for natural persons, use the Sources endpoint in the Persons folder. ``` GET https://api.signicat.com/info/lookup/sources/person ``` The response will contain an updated list of the data sources used in the Data Verification API. :::tip Data sources table Visit the Coverage overview page to view all the data sources supported by the Data Verification API. To learn more about each data source, go to the [Data sources](/docs/data-verification/data-sources/) page. ::: --- ## Release notes for Signicat Data Verification API # Data Verification API release notes --- ### 11.12.2025 #### New sourceSpecific field is now available in the Ownership endpoint ##### Features - The new optional `sourceSpecific` field is now available in [Organizations Ownership endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetOwnership_GET) responses. - The field conveys extra source-specific information such as - Number of shareholders - Purpose - Registration date - Industries - Addresses - Unidentified shareholder counts - The field can appear - At the top level of the response - Inside the top-level entity (for example: `attribute.sourceSpecific`) - This functionality is backwards-compatible. If no extra data exists, the object is `null`. - Fields inside `sourceSpecific` vary by source but are stable for the same source. ##### Sample response :::details Expand/collapse sample response ``` json { "companies": [ { "name": "LION BIDCO AS", "organizationNumber": { "domestic": "NO922093032", "dunsNumber": null, "legalEntityIdentifier": null }, "percentage": 100, "percentageRange": null, "votingRights": null, "votingRightsRange": null, "integratedOwnership": 100, "integratedOwnershipRange": null, "sourceSpecific": { "description": "Investeringsvirksomhet og i den forbindelse, direkte eller indirekte, eie eller forvalte aksjer og andre verdipapirer og drive tilhørende virksomhet.", "purpose": "Investeringsvirksomhet og i den forbindelse, direkte eller indirekte, eie eller forvalte aksjer og andre verdipapirer og drive tilhørende virksomhet.", "registrationDate": "2019-01-08T00:00:00.000Z", "industries": [ { "58.29": "Other software publishing" }, { "70.10": "Activities of head offices" } ], "address": { "street": "c/o Signicat AS Beddingen 16", "postalCode": "7042", "city": "TRONDHEIM", "country": "NO" } } } ], "persons": [], "otherShareholders": [], "sourceSpecific": { "shareholderDataCompleteness": 24.6, "totalShareholders": 732, "directShareholdersCount": 1, "legalPersonShareholdersCount": 300, "unidentifiedShareholdersCount": 109, "unidentifiedOwnershipPercentage": 70.4, "maxOwnershipDepth": 11, "highVotingLowOwnershipCount": 0 }, "metadata": { "sources": [ "t-rank-evry" ], "urls": [], "lastChanged": "2025-12-10T02:02:29.000Z", "rawJson": null, "isCache": false } } ``` ::: --- ### 25.09.2025 #### New data source supported by the API: OpenRegisters (Kausate) **Data source:** `open-registers` [OpenRegisters (Kausate)](https://www.kausate.com/) provides data and documents for organisations in Germany through the German Handelsregister (trade registers). The data source allows you to retrieve real-time current and chronological entity information, shareholder lists, articles of association and structured information on a company. ##### Features - OpenRegisters (Kausate) is now available as a data source in the Data verification API to look up and verify organisation data in Germany. - You can use the data source by specifying the query parameter `?source=open-registers` in the API request to the following endpoints: - [Organizations Search endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Search_GET) - [Organizations Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) - [Organizations Roles endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET) - [Organizations Documents endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Documents_GET) --- ### 18.12.2024 #### New data source supported by the API: Kontakt- og reservasjonsregisteret (KRR) **Data source:** `krr` [Kontakt- og reservasjonsregisteret (KRR)](https://eid.difi.no/en/common-contact-register) provides email and phone number details for individuals in Norway. The data source allows you to retrieve information that you can use to send messages and documents electronically to your users. ##### Features - KRR is now available as a data source in the Data verification API to look up and verify personal electronic contact information of people registered in Norway. - You can use the data source by specifying the query parameter `?source=krr` in the API request to the following endpoints: - [Persons Contacts endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetContacts_GET) --- ### 26.11.2024 #### New industry codes in Det Centrale Virksomhedsregister (CVR) **Data source:** `dk-cvr` The Central Business Register (Det Centrale Virksomhedsregister, CVR) is the official registry of businesses and organisations in Denmark. ##### Features The Danish Business Authority will update the industry codes (referred to as *Branchekode* in Danish) effective from the 1st of January 2025. In particular, certain companies will receive a new industry code as a result. Learn more in the [Danske Branchekoder 2025](https://www.dst.dk/da/Statistik/dokumentation/dansk-branchekode-opdateres) page on the Danmarks Statistik website. In the Data Verification API, this update will impact the `industries.code` property in responses from the [Organisations - Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo). ### 01.07.2024 #### Companies House data source is now available in the API **Data source:** `companies-house` [Companies House](https://www.gov.uk/government/organisations/companies-house) is the official agency responsible for maintaining the register, and incorporating all forms, of companies in the United Kingdom. ##### Features - Companies House is now available as a data source in the Data verification API to look up and verify organisation data in the United Kingdom. - You can use the data source by specifying the query parameter `?source=companies-house` in the API request to the following endpoints: - [Organisation Basic endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) - [Organisation Roles endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET) - [Organisation UBO endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetUbo_GET) --- ### 10.04.2024 #### Schufa Identity Check data source is now supported in the API **Data source:** `schufa` ##### Features - The data source Schufa Identity Check (`schufa`) is now integrated into the [Identity verification endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_VerifyAddress_GET). - The data source `schufa` is available to verify a natural person's identity information in Germany. - Use `schufa` to verify personal information when you want to ensure real-time validation during onboarding or re-validate data in a Know Your Client (KYC) process. :::note About Schufa [Schufa Holding AG](https://www.schufa.de/) is a German private credit bureau supported by creditors. Learn more about Schufa at [https://www.signicat.com/registry-methods/schufa](https://www.signicat.com/registry-methods/schufa). ::: When sending requests to the Identity verification endpoint, you can use the following input parameters: `country`, `givenName`, `surname`, `dateOfBirth`, `street`, `postalCode`, `city`, `gender` and `phoneNumber`. Learn more about the Identity verification endpoint in the [API overview](/docs/data-verification/api-overview.mdx#identity-verification) documentation. --- ### 03.04.2024 #### Bisnode Consumer Intelligence (dnb-ci) data source is now supported in the API **Data source:** `dnb-ci` ##### Features - The data source Bisnode Consumer Intelligence (`dnb-ci`) is now integrated into the [Identity verification endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_VerifyAddress_GET). - The data source `dnb-ci` is available to verify a natural person's identity and address information in Norway, Sweden, Denmark and Finland - providing comprehensive country coverage. - Use `dnb-ci` to verify personal information when you want to ensure real-time validation during onboarding or re-validate data in a Know Your Client (KYC) process. When sending requests to the Identity verification endpoint, you can use the following input parameters: `country`, `givenName`, `surname`, `dateOfBirth`, `street`, `postalCode`, `city`, `gender` and `phoneNumber`. Learn more about the Identity verification endpoint in the [API overview](/docs/data-verification/api-overview.mdx#identity-verification) documentation. :::tip Note To ensure a better hit on the results, provide as many input parameters as possible in your API request. ::: --- ### 20.01.2024 #### Renamed Information Service API to Data Verification API ##### Features - The Information Service API has now been renamed to Data Verification API. The API URL remains the same: `https://api.signicat.com/info/lookup/`. --- ### 06.11.2023 #### Introduced the Identity verification endpoint **Endpoint:** `identity` ##### Features - Added new **Identity verification** method - GET `/info/lookup/countries/{country}/persons/identity/verify`. :::tip Identity verification With the Identity verification endpoint, you can verify a natural person's identity and address information. Learn more in the: - [Identity verification documentation](/docs/data-verification/api-overview.mdx#identity-verification) - [Identity verification API reference](pathname:///apis/data-verification/#tag/Persons/operation/Person_VerifyAddress_GET) ::: ##### Features (deprecated) - The **Address verification** endpoint is no longer available. :::warning Note Existing customers using the Address verification endpoint are not impacted. ::: --- ### 02.11.2023 #### Bisnode data source is now available in the Basic endpoint **Data source:** `bisnode` ##### Features - The data source Bisnode is now integrated in the [Persons Basic endpoint](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetBasic_GET). :::note All supported endpoints You can use `bisnode` in the following endpoints: - [Persons Basic](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetBasic_GET) (New feature) - [Persons Finance](pathname:///apis/data-verification/#tag/Persons/operation/Person_GetFinance_GET) - [Organization Finance](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetFinance_GET) ::: --- ### 31.10.2023 #### Trapets data source supports Adverse Media in Screening endpoints **Data source:** `trapets` ##### Features - The data source Trapets (`trapets`) now supports `adverseMedia` in the `listType` for the screening endpoints. You can retrieve Adverse Media information both with the [Organization Screening endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Screening_GET) and the [Persons Screening endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/PersonGlobal_Screening_GET). Trapets provides global geographical coverage. :::warning Note `adverseMedia` is only available if you are using a production account. The feature is not available for sandbox accounts and a response error is returned instead. ::: :::note All supported list types for screening When requesting `trapets` data from the screening endpoint, you can choose among the following `listType` fields: - `pep` - `sanction` - `adverseMedia` (New feature) ::: #### Roles endpoint mapping logic updated **Endpoint:** `roles` ##### Changes - Minor technical mapping adjustments to the values returned in the [Roles endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET). --- ### 08.06.2023 #### Norway business register (NO-Brreg) added to Roles endpoint **Data source:** `no-brreg` ##### Features - Data source for Norway business register `no-brreg` is now available in the [Roles endpoint](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET). Customers can now fetch all the roles associated with an organisation using `no-brreg`. :::note All supported endpoints You can use `no-brreg` in the following endpoints: - [Basic](pathname:///apis/data-verification/#tag/Organizations/operation/GetBasicOrganizationInfo) - [Authorization](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetAuthorization_GET) - [Search](pathname:///apis/data-verification/#tag/Organizations/operation/OrganizationGlobal_Search_GET) - [Roles](pathname:///apis/data-verification/#tag/Organizations/operation/Organization_GetRoles_GET) (New feature) ::: --- ### 22.03.2023 #### Surepay v2.0 **Data source:** `surepay` ##### Features - Surepay v2.0 is now integrated in the [Data Verification API](/apis/data-verification/). - Surepay is now available to verify account holders in France. ##### Changes - Minor technical mapping adjustments to the existing Surepay integration. :::warning Note Existing clients using the Surepay integration will not be impacted. ::: To learn more, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Digital Evidence Management (DEM) Signicat's Digital Evidence Management platform (DEM) is a RESTful web service that allows you to securely capture, store and manage audit trail data. This can include information on authentications, payment transactions or acceptance of GDPR consent messages and enables you to efficiently handle audits and inspections. The stored data can be secured, or sealed, using Signicat's [Qualified Timestamping Authority (QTSA)](#sealing-with-qualified-timestamps) services. DEM can be used for full audits of identity verification, authentication and signature processes and complies with [Payment Services Directive (PSD2)](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2) Dynamic Linking requirements. Data that is stored using Signicat's Digital Evidence Management platform is owned and controlled by you, as the customer, who can add, retrieve and delete transaction data and relevant metadata on demand. You determine expiry date, or Time to Live (TTL), for stored data and can search both system-provided and custom user-provided metadata in real time. Signicat acts as the data processor. ### What data is stored? Signicat's Digital Evidence Management platform stores the following data: - [**System metadata**](#metadata) provided by Signicat. - [**Custom metadata**](#metadata) provided by you, as the customer. - A **custom payload** - This is the object that is protected by a timestamp. - A **secured timestamp object** - This will be used for validation of the payload. ### Supported use cases You can define and control use cases based on your business needs. Examples of common use cases for DEM can include: - **Payment transactions** - Determine when a payment was made, what payment channel was used and if the payment triggered Strong Customer Authentication (SCA). - **GDPR** - Audit consent, information rights and the right to be forgotten. - **Know your customer (KYC) and Anti Money Laundering (AML)** - Retrieve events related to KYC and AML. - **Fraud detection and prevention** - Prevent, trace and find evidence of fraud attempts. - **Dispute handling** - Establish complaint handling mechanisms. ## Getting started To access the DEM API, you will need a valid API client, which is a `client_id`/`client_secret` pair associated with either your organisation or with one of your accounts. The API clients are used to obtain access tokens, which are required by all DEM operations for API authorisation. You can have multiple API clients for one account. These clients can have the following permissions, or a combination of them: - **Write** (able to store records) - **Read** (able to retrieve or search for records) - **Update** (able to update Time To Live (TTL) of records) When you have your API client, you must obtain an access token using the OAuth 2 protocol. This is required to consume Signicat's REST services. For general information on how to do this, refer to our [Quick start guide](/docs/eid-hub/quick-start/). ## API reference In our Digital Evidence Management API reference, you can find information about the available endpoints and properties, as well as sample requests and responses. * [**Digital Evidence Management API**](/apis/digital-evidence-management/): Our REST API for capturing audit trail data ## Using the API The Digital Evidence Management API is used to store audits of transactional data or consent messages. A basic process varies, but will start with the following steps: ### Step 1: Obtain an access token Acquire an access token using the OAuth 2.0 protocol. The following is a cURL example of a request to receive an access token: ```bash curl --location --request POST '/auth/open/connect/token' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` ### Step 2: Create a new record To create a record, make a [POST call to the records endpoint](pathname:///apis/digital-evidence-management/#operation/postNewRecord). There are four required parameters: `type`, `TTL`, `metadata` and `coreData`, as well as two optional parameters: `relations` and `auditLevel`. #### Record types Currently, the available record types are `GDPR`,`TRANSACTION`, `LOG_IN`, `SIGNATURE`, `SENSITIVE` and `OTHER`. #### Time To Live (TTL) Specifying the Time To Live (TTL) of a record is mandatory. TTL is defined as a positive integer of 2 or higher. This value indicates the number of days until the record is deleted. :::tip Note A separate [POST call to the records endpoint](pathname:///apis/digital-evidence-management/#operation/setExpiryDate) to set the expiry date for a given record is also available. This call allows you to **redefine** the TTL of a record in case you would like to change the expiry time of the specified record after the record has already been created. ::: #### Metadata The main purpose of metadata is to help in the construction of efficient search operations. Some **system metadata** is automatically added to records by Signicat. System metadata includes: - The type of event (GDPR, transaction, etc.) - The time from a timestamp - Time To Live (TTL) You can define **custom metadata**. Examples of custom metadata are: - Names - Payment amounts - Issuing bank account and beneficiary bank account #### Coredata The `coreData` field contains the data you want to protect and timestamp. In many cases, you will want to duplicate some of the metadata elements in the `coreData` payload. Other elements of the payload can be authentication information such as a [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519), certificates or SAML assertions. You can also include other objects such as image files. All binary data in the payload JSON structure needs to be BASE64-encoded. #### Relations The optional `relations` element can contain data on relations to other records. #### Audit levels The optional `auditLevel` element determines the level of timestamping and verification applied to the record. Signicat's DEM service only supports the `QUALIFIED` audit level. - `QUALIFIED`: This option uses Signicat's [Qualified Timestamping Authority (QTSA)](/docs/qtsa/) to create a valid qualified timestamp token, which is stored to ensure the record can be validated. The time from the timestamp object is used in the system attributes (defined as `system.`). :::note Deprecation Notice The `SIMPLE` and `ADVANCED` audit levels are deprecated and no longer supported. ::: #### Request example The following example request body shows how to create a new record. ```json { "type":"SIGNATURE", "TTL":2, "metadata":{ "searchable_metadata": "searchable_value", "Jaffa_cake":"is not a biscuit", "number":42 }, "coreData": { "secret":"Sealed and safe" }, "relations":[ "" ] } ``` :::warning Important For the time being, the maximum record size is 10 MB. ::: ## Other integration details Once you have created a record, you can carry out different actions depending on use case: - The [**records endpoint**](pathname:///apis/digital-evidence-management/#tag/records) allows you retrieve a list of records that match specific parameters. You can also retrieve individual records based on their ID and redefine the TTL of a record. - The [**info endpoint**](pathname:///apis/digital-evidence-management/#tag/info) allows you to retrieve statistics on records in the database, such as custom metadata fields you have used. ### Searching for records To search for a record, make a [POST call to the records endpoint](pathname:///apis/digital-evidence-management/#operation/query). The query body consists of one or more operators (`and`, `or`). Each operator contains an array of several query objects. Each query object has 3 fields: - `field`: The metadata field the operator should be applied to. Note that system attributes are defined as `system.` and user-defined fields as `custom.`. - `operator`: The search operator (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`) - `value`: The value the operator will use for the query The available operators are: - `eq`: equal to - `ne`: not equal to - `gt`: greater than - `gte`: greater than or equal to - `lt`: less than - `lte`: less than or equal to - `in`: `field` value in given array (value input) - `nin`: `field` value not in given array (value input) - `contains`: `field` value matches regex (value input) #### Request example The following example request body shows how to search for a record. ```json { "and": [ { "field": "system.type", "operator": "eq", "value": "SIGNATURE" }, { "field": "custom.numberField", "operator": "lt", "value": 42 } ] } ``` ### Retrieving records To retrieve a previously created record, make a [GET call to the records endpoint](pathname:///apis/digital-evidence-management/#operation/getRecordById). You can retrieve individual records based on their ID. This GET call also validates the `coreData` payload to detect changes, using a secured timestamp object. You can read more about timestamping in the section on [Sealing with qualified timestamps](#sealing-with-qualified-timestamps) below. :::warning Important The ID you supply must conform to the UUID/GUID standard. Example: `123e4567-e89b-12d3-a456-556642440000`. This returns everything included in the record entity. ::: ### Sealing with qualified timestamps Signicat can seal and secures critical data elements such as the subject and the consent that was given. This can be done by adding a qualified timestamp to these data elements using Signicat's [Qualified Timestamping Authority (QTSA)](/docs/qtsa/) services. Timestamping data elements allows you to detect if the data has been modified and will bind the data to a proven time. The elements are then validated on retrieval. --- ## Authentication REST API The Signicat Authentication REST API enables you to authenticate your end-users in an easy and secure way. With the Authentication REST API, you can implement various authentication flows in your backend systems. This authentication method offers less complexity when integrating compared to OIDC and SAML 2.0. Compared to OIDC or SAML 2.0, the Authentication REST API's main advantages are: - **REST standard**: Since this is just a very simple REST API, you do not need to implement complex protocols. - **Wide support**: The API supports complex flows such as the headless flow. However, note the following limitations: - You always need a backend system to call the API securely. - You may have to write more custom code instead of relying on an SDK like for OIDC and SAML. ## Available flows The Authentication REST API supports the following authentication flows: - [Redirect flow](#redirect-flow) - [Headless flow](#headless-flow) - [Embedded flow](#embedded-flow) Learn more about each flow below. ### Redirect flow The redirect flow allows you to pass a URL to your end-users which they will open in a browser. In a redirect flow, end-users are redirected several times during the authentication session. At the end of this redirect chain, end-users are routed to the success `callbackUrl`, which corresponds to a location in your backend. Then, you can consume the result from the authentication session from the Authentication REST API. This includes information about the authenticated user (for example, subject). Sequence diagram example ### Headless flow A headless flow, in the context of authentication and APIs, refers to a process that occurs without user interface (UI). In a headless flow, the frontend and backend components are decoupled allowing for greater flexibility to deliver multiple services that interact with the same backend service. The headless flow allows you to provide your own user interface within your app or website. Requests are sent from your backend server to Signicat's Authentication REST API. Headless flow is currently only available for the following eIDs: - [Auðkennisappið](/identity-methods/audkenni-app/setup/#headless-flow) - [itsme® - Headless for mobile App2App flows](/identity-methods/itsme/integration/app2app.mdx) - Mobiil-ID - Documentation coming soon - [Norwegian BankID - Headless flow](/identity-methods/nbid/integration-guide/auth-api-nbid/headless-nbid.mdx) - Smart-ID - Documentation coming soon - [Swedish BankID - Headless flow](/identity-methods/sbid/integration-guide/auth-rest-api/headless.mdx) ### Embedded flow Embedded flows enable you to render the authentication flow inside an iframe in your application (as opposed to the redirect flow where you are redirecting the user to another page). In an embedded flow, the authentication journey happens inside a component, like an iframe, embedded within your UI. In this scenario, your application manages the iframe and polling logic, creating a hybrid integrated experience for your end-users. We support embedded flows for the following eIDs: - [Norwegian BankID](/identity-methods/nbid/integration-guide/auth-api-nbid/embedded-nbid/) - [Swedish BankID](/identity-methods/sbid/integration-guide/auth-rest-api/embedded/) - [Email OTP](/identity-methods/email-otp/setup/authentication-api/embedded/) - [SMS OTP](/identity-methods/sms-otp/setup/authentication-api/embedded/) ## API reference In our Authentication REST API reference, you can find information about the available endpoints and properties, as well as sample requests and responses. * [**Authentication REST API**](/apis/eid-hub/): Configure your Authentication REST API ## Tutorial video This video shows you how to configure the Authentication REST API for the Signicat eID and Wallet Hub in the Signicat Dashboard. --- ## Migrating from Express For the Signicat Digital Trust Platform (DTP), we have made the Signicat Authentication REST API more tightly integrated with the platform to take full advantage of its possibilities. However, we have taken care to make the migration from the old API in Express as seamless as possible. ## Key differences - [Authorization](#authorization): DTP does not use the same access and identity and access management (IAM) control as Express. - [Endpoints](#endpoints): The general flow is the same, but with minor differences. - [Data models](#data-models): The request and response objects have slightly different structures. - [Encrypted responses](#encrypted-responses): DTP does not sign encrypted responses. In addition, there are some general differences between Express and DTP such as the concept of organisations and accounts, eIDs, platform differences. You can find more information about these concepts in the [Glossary](/docs/dashboard/glossary.mdx). ## Authorization Signicat DTP features a richer and more powerful access and IAM control. Although technically different, it is practically similar as it is still using an OAuth2 client credentials flow. In short, you need to use a new token URL, a new client (client ID and client secret) and a different scope. :::info Want to learn more? For more information on how to authorize, see the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). ::: ## Endpoints We have made some minor changes to our endpoints, but the general structure remains much the same. :::CustomTable{columnWidths="33% 33% 33%"} | **Name** | **Endpoint** | **Change** | | :----------------- | :------------------- | :----------------------------------- | | Create session | `POST /sessions` | New parameter, `signicat-accountId`. | | Retrieve session | `GET /sessions/{id}` | New parameter, `signicat-accountId`. | | List sessions | `GET /sessions/{id}` | This endpoint has been deprecated. | | Invalidate session | `GET /sessions/{id}` | This endpoint has been deprecated. | ::: :::warning Deprecated endpoints "List sessions" and "Invalidate session" have been deprecated because of a different way of treating non-permanent data in DTP. When a session expires in DTP (with `sessionLifetime`), it's completely deleted from our system. It's done this way to increase protection of PII and simplify data management. ::: ## Data models We have improved the structure of the [request](#request) and [response](#response) objects to make them clearer and more concise. ### Request :::CustomTable{columnWidths="33% 33% 33%"} | **Old name (Express)** | **New name (DTP)** | **Comment** | | :-- | :-- | :-- | | `allowedProviders` | `allowedProviders` | Same field name, but new values: `["nbid", "sbid"]`. | | `include` | `requestedAttributes` | New field name and new values (see [API specification](/apis/eid-hub/) for details). | | `redirectSettings` | `CallbackUrls` | New field name and new values: `["success", "abort", "error"]`. | | - | `sessionLifetime` | New field (not required). | | - | `themeId` | New field (not required). | ::: ### Response :::CustomTable{columnWidths="33% 33% 33%"} | **Old Name (Express)** | **New Name (DTP)** | **Comment** | | :-- | :-- | :-- | | `url` | `authenticationUrl` | New field name, but the same purpose. | | `status` | `status` | Same field name, but values are capitalised. | | `identity` | `subject` | New field name and new values: (see [API specification](/apis/eid-hub/) for details). | | `identity.providerId` | `subject.idpId` | New field name, but the same purpose. Field representing the user's unique ID from the eID. | ::: ## Encrypted responses Although it is possible to encrypt the response you receive from Signicat, DTP does not sign the response (with a digital signature). This means that you only need to decrypt the response, as explained in [Encrypted responses from Signicat](/docs/eid-hub/authentication-api/receive-encrypted-responses.mdx) page. --- ## Receive encrypted responses from Signicat Signicat can send encrypted responses. This means we will encrypt the responses on the given session. All responses from Signicat are fully encrypted on the transport layer with HTTPS. You can implement message-level encryption (MLE) as an additional security layer. This section explains how to set up and process encrypted responses. :::warning Important For FTN, you are required to receive encrypted responses. If you do not set this up correctly, FTN will fail and you will not be able to obtain any FTN authentication results. ::: ## Prerequisites To use encrypted responses, you must first generate a key pair. :::tip Note You can use our website [JWK generator by Signicat](https://jwk-gen.signicat.guru/) to securely generate this key pair, or any other method that is convenient for you; for example, OpenSSL, or a JOSE or JWK library for the language of your choice. ::: 1. The key pair needs to be in a valid JWK format. 2. The technical requirements for the keys are: ### For RSA key types :::CustomTable{columnWidths="50% 50%"} | **Field name** | **Value** | | :---------------- | :--------- | | Algorithm (`alg`) | `RSA-OAEP` | | Key type (`kty`) | `RSA` | ::: For RSA, we support key sizes of 2048 bits and 4096 bits if required. ### For elliptic curve key types :::warning Note Support for Elliptic curve cryptography (ECC) key pairs will be available soon. ::: :::CustomTable{columnWidths="50% 50%"} | **Field name** | **Value** | | :---------------- | :------------------------ | | Algorithm (`alg`) | `ECDH-ES` | | Curve (`crv`) | `P-256`, `P-348`, `P-521` | | Key type (`kty`) | `EC` | ::: ## Implementation To implement encrypted responses, you need to include the additional field `encryptionPublicKey` when making a request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. You can find more details about this field in our API specifications. Following this, all of your responses for both the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) and the [Get session status](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) endpoints will be encrypted with this key. The responses will also be encrypted in our session storage. This ensures full encryption in the Authentication REST API. ### Example request ```json { "allowedProviders": ["nbid"], "flow": "redirect", "requestedAttributes": [ "firstName", "lastName", "dateOfBirth", "nin" ], "callbackUrls": { "success": "https://postman-echo.com/get?status=success", "abort": "https://postman-echo.com/get?status=abort", "error": "https://postman-echo.com/get?status=error" }, "encryptionPublicKey": { "alg": "RSA-OAEP", "e": "AQAB", "kty": "RSA", "n": "1soz_f_GSGVYfYwIRSu6mkIsyymeqjEXdO-24ffhZnrwKNEeqO9vwxVKHpAUMA55QGBhPl-epJjYjzy_24n-0qvJEwddLvo0cuO0N-ms0LhB8WlUwhLKp6pqj_AO46Pt7qyBNFlWQh3KF_UakAb1Jq1P97Ba0FAIXJBaTKvnZ5hxwJY5i2tPA_NNQT5D40nqc0BNWS0Iv6Ww9oYfQn3pecyOygTFGMTg2SQ3t-4XRGaKclOwExIWTJTv21slOBMJQLomO0hJtnRAB9aBZRgit8K41TzuBp_wpbFlYLoep8lRyG-n2A_1yHlww1P2pVzmlynNDO87ERek6EyI6uPZvQ", "use": "enc" } } ``` ### Example response ```http HTTP/2 200 Content-Length: 2048 Content-Type: application/jose Date: Tue, 07 Feb 2023 15:08:43 GMT eyJh...QifQ.Qq5TQR...xN-PQ.ojSGehTV7xw_xE078sFnTg.in8a...SITqA.SyVNrXe0C3UkKBQ_AVyQiw ``` The response will now say `Content-Type: application/jose` instead of the usual `Content-Type: application/json`. This tells you that the response is a JWE (JWT) as per [RFC 7516: JSON Web Encryption (JWE)](https://www.rfc-editor.org/rfc/rfc7516). You can now use your private key from the key pair you created earlier to decrypt this message. The payload of the JWE is a JSON structure that is exactly the same as a non-encrypted reply, so you will be able to continue with your normal implementation once you have decrypted the payload. ## Example code :::warning Important This code example is for illustrative purposes only. It is not intended for use in production. Signicat will not be held responsible if this code example is used inappropriately. ::: ```python from jwcrypto import jwk, jwe # ATTENTION: Insert your nested JWT (that you received from the Signicat Authentication REST API) here. jwe_serialized = "eyJh...QifQ.Qq5TQR...xN-PQ.ojSGehTV7xw_xE078sFnTg.in8a...SITqA.SyVNrXe0C3UkKBQ_AVyQiw" # For the sake of simplicity in this example, the JWKs have been manually loaded into a dictionary. # In practice, you should do this in a secure manner. The jwe_private_key should be stored securely on your premises. jwe_private_key = { "alg": "RSA-OAEP", "d": "IchOWqQUx_S2sRJqB5Ub5aDEYlTiuXJ8tb3xRgPCjieGZ-kSOTBlo-mQjZOMNU3FeOBf0xtffJR0tTyxEWLYM0LlHorRN28PekWBpiyo63AboRB3zgl-GdZmKcrwUJILPXeg376wYDhGvbNlkOMjQkjOk87HTc3Urthed4IvJH4N7SpHBuzFHucb_1Zcq7i_UZrvQecNZoODoeTJIeaN4LoN4AB63Jc75doVBvTqyyKl39VdrdDzsv17WOq_HjFe0KLwFGjK6VEQbiaNMS7Jh6XoKVkiVLKT2uzyzpWCHu68gB6BDuItlllhbMYYCW9yoC7mFkWroG_EZj8PJL-58Q", "dp": "UU2ygH3JEjmyTEiOmNHSpoDjnn5JR0nmZDZ4AOrEUMuMmXbnkNfXN5vGmo8hBZbWUBcXN5CkeGysiFByldfw1oVRlNoA1np00Gtb_8RsaElcIr1aWSgACArCsbhplDNSzNDPjm6FvW21Rkdm0AwVmak7YgtMgodq1TLBUwd_-uE", "dq": "VqinrWjEIgryjHdQmb_cFhxGFN167EvM5PSjrj3w1Dg6453MKZjriJmIT8LZbbcrLalkaeje2PK0Koy1ZEyBvmRHlZDShX8AigXeY2s478wWVk03bsJyWcrMO2Lokal_Zn6_ULJYkmIHPoXzzB56odEqxgQnP1ZM0O0nS2J76k0", "e": "AQAB", "kty": "RSA", "n": "1soz_f_GSGVYfYwIRSu6mkIsyymeqjEXdO-24ffhZnrwKNEeqO9vwxVKHpAUMA55QGBhPl-epJjYjzy_24n-0qvJEwddLvo0cuO0N-ms0LhB8WlUwhLKp6pqj_AO46Pt7qyBNFlWQh3KF_UakAb1Jq1P97Ba0FAIXJBaTKvnZ5hxwJY5i2tPA_NNQT5D40nqc0BNWS0Iv6Ww9oYfQn3pecyOygTFGMTg2SQ3t-4XRGaKclOwExIWTJTv21slOBMJQLomO0hJtnRAB9aBZRgit8K41TzuBp_wpbFlYLoep8lRyG-n2A_1yHlww1P2pVzmlynNDO87ERek6EyI6uPZvQ", "p": "2m4looTgE4Gx8Uu8mTjv3PGlHLYuG5zTIJAG9joxnOO-JdvIwUIi4Kc4QN-cJJpZsdpBQs5HKcI4F6TFccO_lx7q4xgXgzGBTMy6lLsYgFgIBM0SWXqQ3Ws35ewt40v9Zhs0kaRSpzuS0Pik90cwsPcMexB2BJ3kTSEgMctEDLE", "q": "-7vDS1Cu9RuXX7Xktg6Ftn-FGiCQQ26is7s-ixwv0XGhV2nxzzKKhNcattYWFnOAA91NOzBy8XWaDMli2vNqqSlcDnvAZGpppv-nJRD3wyVvcYWV3Bi_xGsjh5NiyEC8RQOj5rzZ9jP3EJdw3pvfAZj_ncSfwpuGH9ESPaJssM0", "qi": "coF8GU0fQ9-KcZfz2Vp8Si4MwzQElFwaAkJX64cZe57-IjDYWlU66VMB1tsoJbCWt_vWOSmOCXROVOSYIdI85y_W2PtSjRGxKInMlQ7MGpqhAVv75nD_k0yf2y8AFZk4SCoiVFlQWJ44Ke8vaf7FTKBCgzbznkY2xvBqYRv7N8Y", "use": "enc" } # Loading JWK key jwk_jwe_private_key = jwk.JWK() jwk_jwe_private_key.import_key(**jwe_private_key) jwetoken = jwe.JWE() jwetoken.deserialize(jwe_serialized) jwetoken.decrypt(jwk_jwe_private_key) payload = jwetoken.payload.decode('utf-8') print(payload) ``` --- ## Test connections This page describes how you can test an authentication with the Signicat Authentication REST API using **Postman**. For testing purposes, this guide shows steps to complete a *redirect flow* using Norwegian BankID. However, you may easily adapt the instructions to test all the other eIDs available in the Signicat eID and Wallet Hub. Additionally, you can find eID-specific test guides in the respect [eID documentation](/identity-methods/). :::tip Sandbox account We recommend you run test authentications by using a sandbox account. ::: ## Initial preparations Before you can run a test authentication, make sure to complete the following configuration in the Signicat Dashboard. :::tip New customers If you are new to Signicat, we recommend you first read the [Get started with Signicat](/docs/) page. ::: ### Add an eID To add an eID to your Signicat account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ### Connect to the API To learn how to connect to this API, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **Authentication REST API** for your API client. ::: ## Test with Postman You can make calls to the Authentication REST API using our Postman collection. :::tip Testing only Note that Postman is a tool for testing and learning about APIs. You should not rely on Postman in production. ::: ### 1. Import the Postman collection You can fork or import the Postman collection by clicking the button below: [](https://app.getpostman.com/run-collection/20756027-56b06e30-202c-43b6-8838-3eb0007ebb39?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D20756027-56b06e30-202c-43b6-8838-3eb0007ebb39%26entityType%3Dcollection%26workspaceId%3D3ea7a3cf-7777-4f42-b4e9-88876cfe660d) To start using the Postman collection, do the following: 1. Fork or import the Postman collection. 2. Open Postman and select the **Signicat Authentication REST API** collection. 3. In the Variables tab, edit the following variables: - `baseURL`: The base URL of the API. Set this to: `https://api.signicat.com/auth/rest`. - `oauth_scope`: The scope. Set this to: `signicat-api`. - `oauth_client_id`: The client ID of your API client. For example, this looks like `dev-red-pin-123`. - `oauth_client_secret`: The client secret associated to your API client. - `oauth_url`: The Authorisation URL. Set this to: `https://api.signicat.com/auth/open/connect/token`. 4. Save your variables by clicking the save icon or pressing Ctrl+S. Now, you are ready to obtain an access token. ### 2. Obtain an access token To authorise requests to the API, you need to pass the access token in your request. To obtain the access token with the Postman collection, do the following: 1. In the Postman collection, select the **Authorization** tab. 2. Scroll to the bottom and select **Get New Access Token**. 3. If the request is successful, review the Access Token and select **Use Token**. You have now obtained the access token to authenticate to the API. When calling an API endpoint, you supply the access token in the HTTP `Authorization` header of your request. :::tip Token lifetime Tokens have a default expiry date. If a token expires, repeat the steps above to request a new token. ::: ### 3. Create an authentication session :::tip Authentication flows This guide shows an example authentication with the *redirect flow*. We also supports other flow types. Learn more in the [Authentication REST API](/docs/eid-hub/authentication-api/index.mdx) documentation. ::: To begin an authentication flow, your application needs to build and direct the end-user to the authentication URL where the end-user can authenticate with their eID, such as Norwegian BankID. To obtain the authentication URL, you send a POST request to the **Create a new session** endpoint with the appropriate parameters in the body of the request. The body of the request might look like this: ```json { "flow": "redirect", "requestedAttributes": [ "IdpId", "nin", ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "allowedProviders": [ "nbid" ], } ``` To create the authentication URL in the Postman collection, do the following: 1. In the left menu, expand the collection and select the **Create a new session** endpoint. 2. Edit the **Body** of your request. For example, you can use the example above. 3. In the endpoint window, select **Send** to send the request. 4. In the response window, select the **Body** tab to view the response payload. 5. Copy and paste the `authenticationUrl` in your browser to start an authentication session with the eID. In this case, this is Norwegian BankID. **Example of response payload** ```json { "id": "181f6409-107b-4ad8-8bd1-3068b0bde9cf", "accountId": "", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=4998966e-78ff-114b-b528-d79d423790a1&transactionId=10e8eead-6fdb-c649-a626-fc7cf12d590e", "status": "CREATED", "callbackUrls": { "success": "https://example.com:443/success?sessionId=181f6409-107b-4ad8-8bd1-3068b0bde9cf", "abort": "https://example.com:443/abort?sessionId=181f6409-107b-4ad8-8bd1-3068b0bde9cf", "error": "https://example.com:443/error?sessionId=181f6409-107b-4ad8-8bd1-3068b0bde9cf" }, "allowedProviders": [ "nbid" ], "language": "en", "flow": "redirect", "requestedAttributes": [ "idpId", "nin", ], "sessionLifetime": 1200, "expiresAt": "2026-05-29T09:04:35.7543967+00:00" } ``` When implementing login with the redirect flow, you should design your application to redirect the end-user to the `authenticationUrl`. ### 4. Authenticate with test users You need a Norwegian BankID test user to complete the authentication. For example, you can use the following credentials: :::CustomTable{columnWidths="33% 33% 33%"} | National identity number | One-time password | Password | | :----------------------- | :---------------- | :--------- | | `01100844350` | `otp` | `qwer1234` | | `10103933108` | `otp` | `qwer1234` | ::: :::tip Test users for Norwegian BankID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: Once you have completed the authentication flow, you can retrieve the response from successful authentication. ### 5. Get the authentication results When using the API, you can check the status of the authentication session at any stage. When the end-user authenticates successfully, you receive the user data attributes in the response. To do this: 1. In the left menu, expand the **id** folder and open the **Get session status** endpoint. 2. To check the session status, select **Send**. This sends an HTTP GET request using the session ID obtained from the **Create a new session** endpoint. 3. Inspect the response in the **Body** tab of the response window. If the authentication was successful (`"status": "SUCCESS"`), you find the end-user data attributes in the `subject` field. ```json { "id": "9588dba1-f1f6-45f2-8f70-a25b6c3ed858", "accountId": "", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=1c5400f8-7933-3f49-8913-a4dd38754c75&transactionId=5291ae63-b355-464e-adc8-1c15363401ff", "status": "SUCCESS", "provider": "nbid", "subject": { "id": "bBl527R7ya3Xp...rQ0lXgh72uoRSnImM=", "idpId": "9578-XXXX-4-243538", "nin": { "value": "01100844350", "issuingCountry": "NO", "type": "BIRTH" } }, "callbackUrls": { "success": "https://example.com:443/success?sessionId=9588dba1-f1f6-45f2-8f70-a25b6c3ed858", "abort": "https://example.com:443/abort?sessionId=9588dba1-f1f6-45f2-8f70-a25b6c3ed858", "error": "https://example.com:443/error?sessionId=9588dba1-f1f6-45f2-8f70-a25b6c3ed858" }, "loa": "high", "allowedProviders": [ "nbid" ], "language": "en", "flow": "redirect", "requestedAttributes": [ "idpId", "nin" ], "sessionLifetime": 1200, "expiresAt": "2026-05-29T09:10:56.9541901+00:00" } ``` :::note Success! You have now completed an authentication flow using the Authentication REST API. ::: ## Next steps Learn more about the Authentication REST API and explore our eIDs documentation. * [**Authentication REST API**](/apis/eid-hub/): Configure your Authentication REST API * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs --- ## Authentication Vault The Signicat Authentication Vault allows you to automatically store the data you receive from an end-user authentication with electronic identities (eIDs). The data you can store includes transaction logs and the personal information of your users. These are stored securely as records in the Signicat [Digital Evidence Management (DEM)](/docs/digital-evidence-management/). You can access and manage the records directly in the Signicat Dashboard or through the DEM API. To start using the Authentication Vault, you first need to configure it in the Signicat Dashboard. You can find more information on this page. ## How it works An authentication flow typically consists of the following steps: 1. Connect your application to an eID with an authentication protocol. 2. Direct end-users to the authentication server where they verify themselves. 3. Route the end-user back to your digital service. 4. Send backend requests to retrieve the end-user's personal data. 5. Verify and process the end-user's data for your use case. All throughout, your application sends/receives a series of requests/responses to/from the Signicat eID and Wallet Hub. Typically, the data is only available *temporarily* for the scope of the authentication session and is forgotten thereafter. **Why use the Authentication Vault** The Authentication Vault allows you to store the data for longer periods of time beyond the scope of an authentication session. It achieves this by storing the response in the Signicat DEM database, so that you can always retrieve it at a later point. After you activate the Authentication Vault, all your authentication transactions are automatically stored in the DEM database. The data is saved in records that you can view in the Signicat Dashboard and retrieve with the DEM API. **Available settings** The Authentication Vault is configurable and allows you to control the following settings: - Obfuscating the national identity number. - Limiting storage to specific eIDs. - Defining retention periods for records in the DEM database. :::warning Supported authentication protocols The Authentication Vault can help you store records obtained from connections with the following protocols: - OpenID Connect (OIDC) - Authentication REST API (only *redirect flow*) Note that no data is stored for transactions with SAML 2.0. ::: ## Get started To start using the Authentication Vault, you first need to set it up in the Signicat Dashboard. To learn how to set it up, try it out and manage the records, make a selection using the buttons below: * [**Set up**](/docs/eid-hub/authentication-vault/setup): Learn about activating and configuring the vault * [**Try it out**](/docs/eid-hub/authentication-vault/try-it-out): Try out an end-to-end flow to see it in action * [**Manage records**](/docs/eid-hub/authentication-vault/manage-records): Learn about viewing and retrieving records --- ## Manage records On this page, you can learn about: 1. How to view records in the Signicat Dashboard. 2. How to retrieve records with the DEM API. ## View records in the Dashboard You can view and manage your records in the Signicat Dashboard by following these steps: 1. Go to **Dashboard** > **Products** > [**Digital Evidence Management**](https://dashboard.signicat.com/dem). 2. Select a record. 3. Now, you can view the data and manage the record: - To view the raw data in full, select **Expand lines**. - To download the record in PDF format, select **Get report (PDF)**. - To delete the record, select **Delete**. Then, confirm the action in the pop-up box. :::note Expiry date When a record reaches its expiry date, it is deleted automatically and cannot be restored. ::: ### How to search for records Records are assigned a `searchAttribute` to uniquely identify them across services. You can search for records by using the `searchAttribute` attribute field. To search for a record in the Signicat Dashboard, do the following: 1. Go to **Dashboard** > **Products** > **eID and Wallet Hub** > [**Audit logs**](https://dashboard.signicat.com/audit). 2. In the Audit Logs, click your transaction to view its log data. :::tip Filter To filter your authentication transactions, click **Filter** at the top-right corner, then tick **Service Name** and select **Broker**. Additionally, you may also filter by eID by ticking **Advanced > Idp** and selecting your eID. Authentication responses have the `authn_response` type. ::: 3. In the transaction overview, locate the **Summary** on the left-hand side, then copy the **Transaction ID**. You will need this later to identify your record. 4. Click the **Signicat** logo at the top-left corner to return to the Dashboard homepage. 5. Now, go to **Dashboard** > **Products** > [**Digital Evidence Management**](https://dashboard.signicat.com/dem). Here you can view all your records. 6. Click **Add Condition+** and select **AND** in the dropdown menu. 7. In the **Value** field, paste the transaction ID you copied in step 3. For example, the condition should read as `searchAttribute` = `5291ae63-b355-464e-adc8-1c15363401ff`. 8. If a record matches your transaction ID, you will view the record in the results. Then, click the record to view its content. ## Retrieve records with the DEM API You can retrieve records from DEM using the [DEM API](/apis/digital-evidence-management/). Learn more about connecting to the API and accessing records in the [DEM API guide](/docs/digital-evidence-management/#using-the-api). :::warning Important By default, the DEM API is not included in the billing plan for the Authentication Vault. To gain access to the DEM API, you need to purchase it separately, as part of the [Digital Evidence Management (DEM)](/docs/digital-evidence-management/) product. ::: ## Useful links You can read more about Digital Evidence Management in the documentation: * [**DEM documentation**](/docs/digital-evidence-management/): Learn more about the Digital Evidence Management product * [**DEM API reference**](/apis/digital-evidence-management/): Explore the endpoints and attributes of the DEM API --- ## Set it up On this page, you can learn about how to set up the Authentication Vault in the Signicat Dashboard. :::note Supported authentication protocols The Authentication Vault can help you store records obtained from connections with the following protocols: - OpenID Connect (OIDC) - Authentication REST API (only *redirect flow*) Note that no data is stored for transactions with SAML 2.0. ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::info Production account To use the Authentication Vault in a production account, you need to first purchase it. When you are ready to do this, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Dashboard. ::: #### Permissions Since authentication data contains personally identifiable information (PII) of the end-users, the data is stored in DEM using *sensitive* records. For this reason, you should manage access to the records in the Dashboard appropriately. To view, edit and create records from the Authentication Vault, users in the Signicat Dashboard require at least one of the following permissions: - **DemSensitiveViewer**: Access to read sensitive records in DEM. - **DemSensitiveWriter**: Access to read and write sensitive records in DEM. - **DemSensitiveEditor**: Access to read, write and update sensitive records in DEM. To provision these permissions in the Signicat Dashboard, go to **Dashboard** > **Access Management** > [**Permissions**](https://dashboard.signicat.com/ownidp-management/permissions) page. You can learn more about role management in our [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx) documentation. :::note Additional DEM permissions There are more permissions to choose from when handling DEM records, as explained in the [DEM documentation](/docs/digital-evidence-management/). ::: ## Configuration To enable and configure the Authentication Vault in your Signicat account, do the following: 1. Go to **Dashboard** > **Products** > [**eID and Wallet Hub**](https://dashboard.signicat.com/auth). 2. In the left sidebar menu, select **Authentication Vault**. 3. In the Authentication Vault configuration page, set the following attributes: | Attribute | Description | |:--------- |:----------- | | *Status* | Toggle to enable/disable the Authentication Vault product. | | *Time to live (TTL)* | Number of time units (in digits) to store the records for. Must be between 2 days and 84 months. | | *Unit* | Time unit. Choose between "Days" and "Months". | | *Selected authentication providers* | Choose for which eIDs to store data. You must select at least one. | | *Obfuscate NIN* | Determines whether to show or obfuscate the national identity number (NIN) of the end-user. If ticked, NIN is obfuscated. | :::note Note These settings apply only to the Authentication Vault product and do *not* affect the global configuration of Digital Evidence Management (DEM) in your account. You manage, activate and configure the DEM product separately. ::: 4. Select **Save** to save the configuration. This will enable the Authentication Vault in your Signicat account. Your configuration might look like this: Authentication Vault in the Signicat Dashboard :::info What happens next? Once you have activated the Authentication Vault, the data is automatically stored in the DEM database for all future authentication sessions for the eIDs you have configured. Then, the records become readily available for you to view in the Signicat Dashboard. ::: ## Next steps You are now ready to try an authentication test run and manage your records. * [**Try it out**](/docs/eid-hub/authentication-vault/try-it-out): Try out an end-to-end flow to see it in action * [**Manage records**](/docs/eid-hub/authentication-vault/manage-records): Learn about viewing and retrieving records --- ## Try it out On this page, you can learn how to run an end-to-end flow to test the Authentication Vault and how records are generated during a test authentication with Norwegian BankID. **Steps overview** 1. Configure the Authentication Vault to store records for [Norwegian BankID](/identity-methods/nbid/). 2. Run a test authentication session. 3. Review the records in the Signicat Dashboard. ### 1. Configure the Authentication Vault To follow along this tutorial, configure your Authentication Vault, as follows: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**Authentication Vault**](https://dashboard.signicat.com/bca/authentication-vault/edit). 2. In the Authentication Vault configuration page, set the following attributes: - **Time to live (TTL)/Unit**: 2 Days - **Selected authentication providers**: Norwegian BankID - **Obfuscate NIN**: 3. Click **Save** to update the configuration. ### 2. Try out an authentication To test an authentication with a test user, follow the guide for the respective authentication protocol: - [Test connections with OIDC](/docs/eid-hub/oidc/test-connections/). - [Test connections with REST API](/docs/eid-hub/authentication-api/test-connections/). To simulate an authentication with a test user, you can use the following test credentials: :::CustomTable{columnWidths="33% 33% 33%"} | National ID | OTP | Password | |:------------- |:----- |:---------- | | `01100844350` | `otp` | `qwer1234` | ::: :::tip Test users for Norwegian Bank ID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: ### 3. Review the records Once the authentication completed successfully, the records become available in the Signicat Dashboard. To view the record of your authentication, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**Digital Evidence Management**](https://dashboard.signicat.com/dem). 2. Select a record. 3. Click **Expand lines** to view the raw data (JSON). **Example raw data** ```json { "id": "", "metadata": { "searchAttribute": "b1a1f071-8273-e04c-82db-eb03d14d1228" }, "systemMetadata": { "type": "SENSITIVE", "expiryDate": "2024-06-23T00:00:00Z", "createdDate": "2024-06-21T00:00:00Z", "createdDateTime": "2024-06-21T07:35:01Z", "createdBy": "", "auditLevel": "QUALIFIED" }, "coreData": { "response": { "subject": "cpPchEZj4bUtjH6ZKXVmVD8COVKHzei7s9LPT2MCTM4=", "subjectType": "PERSISTENT", "issuer": "https://auth.current.bankid.no/auth/realms/current", "idp": "nbid", "loa": "high", "transactionId": "b1a1f071-8273-e04c-82db-eb03d14d1228", "attributes": [ { "name": "nbidSid", "dataType": "string", "value": "d36d3efd-b973-4cbb-9856-f0901b182593" } ], "standardAttributes": { "name": { "fullName": "Gustavo Silva", "firstName": "Gustavo", "lastName": "Silva" }, "nin": { "value": "***", "issuingCountry": "NO", "type": "BIRTH" }, "dateOfBirth": "1908-09-29" } } }, "timestampData": { "timestamp": "MIIJCzADAgEAMIIJAgYJKo...q9cpN2WSu5e/", "timestampValid": true }, "relations": [ { "relationID": "", "type": "SENSITIVE", "_links": { "self": { "href": "https://api.signicat.com/dem/records/" } } } ], "_links": { "self": { "href": "https://api.signicat.com/dem/records/" } } } ``` Note the following relevant fields: :::CustomTable{columnWidths="25% 75%"} | Attribute | Description | |:------------------- |:----------- | | `id` | Record ID in UUID/GUID standard. You can use this in your requests to the DEM API to retrieve the record. | | `metadata` | Searchable field to filter records in DEM. | | `systemMetadata` | Metadata object with information about creation and expiry date, source and record type. | | `systemMetadata.type` | The type of the record. Always set to `SENSITIVE` when using the Authentication Vault. | | `systemMetadata.auditLevel` | The level of timestamping and verification applied to the record. Always `QUALIFIED`. | | `coreData.response` | Authentication response containing personal information of the end-user. Note how `nin` is obfuscated `***` in this example, according to the Authentication Vault configuration. | | `timestampData` | Qualified timestamp generated by Signicat's [Qualified Timestamping Authority (QTSA)](/docs/qtsa/). | ::: :::info Success! You have completed an authentication with Norwegian BankID and stored your record in DEM. ::: ## Next steps Learn about the different ways to access your records. * [**Manage records**](/docs/eid-hub/authentication-vault/manage-records): Learn about viewing and retrieving records --- ## IdP scoping IdP scoping allows you to define which eIDs to make available for authentication to your users. One of the advantages of using IdP scoping is the ability to show only eIDs that are relevant to your users, thus shielding the other eIDs active in your Signicat account. This feature is also known as IdP discovery or IdP routing rules. ## How it works Let's imagine a scenario where you have implemented a login button on your web application, registered it with Signicat eID and Wallet Hub, and have configured multiple eIDs in your account, such as Norwegian BankID and eHerkenning. When a user wants to log in to your app, they click the login button to authenticate with their personal eID credentials. IdP scoping allows you to automatically route the user to the appropriate eIDs (for example only eHerkenning) and shield them from seeing the other eIDs active in your account (in this case Norwegian BankID). You may want to do this for a multitude of reasons, such as geographical relevance. :::tip How to skip the provider selection screen If you specify only one eID in your request, you automatically redirect the user to the authentication page of the eID, thus skipping the provider selection screen. ::: IdP scoping allows you to control the following aspects of an authentication session: 1. [**eID scoping**](#eid-scoping): Defines which eIDs are available for authentication to the user. 2. [**Provider scoping**](#provider-scoping): Further specifies the provider, bank or issuer to make available for an eID. For example, with iDIN you can choose to direct the end-user to _one of_ the issuing banks. Note that only certain eIDs support provider scoping. The rest of this document describes and shows examples to handle both cases. ## eID scoping To use eID scoping, you provide the list of eIDs you want to offer as parameters in the authorisation request. How you specify the eIDs varies per authentication protocol. Here, select the tab of the authentication protocol you use in your integration: When using the OIDC, you can specify the eIDs in the `acr_values` parameter of your authorisation request. In particular, you need to use the `idp` key in the `acr_values` with the format `acr_values=idp:idp_name,other_idp_name`. For example, to display Email OTP and FTN to your end-users, the authorisation request could look like this: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=idp:otp-email,ftn ``` To learn more about `acr_values`, see the [acr_values](/docs/eid-hub/oidc/oidc-implementation.mdx#acr_values) documentation. When using SAML, you can specify the eIDs in the `ProviderID` property of the `IDPEntry` field, as shown below: ```xml {8-12} ENTITY_ID ``` If you define only one eID in the payload, the end-user is routed to the IdP-specific authentication page, automatically skipping the IdP selection screen during authentication. To let the end-user choose among a subset of eIDs active in your account, specify multiple values with the `IDPEntry` field. When using the Signicat Authentication REST API, you can specify the eIDs in the `allowedProviders` field in the payload of the request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, to display Email OTP and FTN to the end-user in the eID selection screen, use: ```json ... "allowedProviders": [ "otp-email", "ftn", ], ... ``` At the start of an authentication flow, the end-user will be able to choose between Email OTP and FTN in the provider selection screen. Provider selection screen :::warning Scoping applies only to active eIDs When using IdP scoping, you can specify only eIDs that are active in your account. ::: :::tip Scoping codes for your eIDs You can find scoping codes for your active eIDs in the **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn) page. You can view a list of codes for the most common eIDs in the [eID scoping codes](/docs/eid-hub/concepts/idp-scoping/#eid-scoping-codes) section below. ::: ### Skip eID selection screen If you define *only one* eID with IdP scoping, then the end-users are automatically routed to the IdP-specific authentication page, thus skipping the IdP selection screen — the page where all your active eIDs are typically displayed at the beginning of end-user authentication. For example, to automatically direct the end-user to SMS OTP, build your authorisation request as shown below. Select the tab according to the authentication protocol you want to use: To automatically direct the end-user to SMS OTP with OIDC, you need to define `acr_values=idp:otp-sms` in your authorisation request: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=idp:otp-sms ``` To automatically direct the end-user to SMS OTP with SAML 2.0, you need to define `ProviderID="otp-sms"` in your `AuthnRequest` request: ```xml {8-12} ENTITY_ID ``` To automatically direct the end-user to SMS OTP with the Authentication REST API, you need to define `allowedProviders` in the body of the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint, as shown below: ```json ... "allowedProviders": [ "otp-sms", ], ... ``` The examples shown above allow you to shield the end-user from seeing other eIDs that are active in your account and route the end-user directly to the eID of your choice. ## Provider scoping Certain eIDs are comprised of a network of identity providers (or issuers), such as banks, that are responsible for authenticating their own customers. Your application can route your end-users automatically to one specific identity provider, by scoping the identity provider in the authentication request. In the table below, you can find parameters for the eIDs that support provider scoping: :::CustomTable{columnWidths="20% 20% 60%" minTableSize="800px"} | eID | Parameter | Providers | |----------|-------------|----------------------------------| | FTN | `ftn_idp` | View the list of FTN issuers in the eID documentation for [FTN](/identity-methods/ftn/attributes-reference.mdx#idp-scoping). | | iDIN | `idin_idp` | Learn more about iDIN issuers in the [iDIN Setup](/identity-methods/idin/setup.mdx#issuer-bank-selection-screen) guide. | | Smart-ID | `dokobit_idp` | Allows you to select the country for an authentication. Possible values: `be`, `ee`, `lt`, `lv`. Learn more in the [Smart-ID](/identity-methods/smart-id/setup/) documentation. | ::: For examples of requests with provider scoping, choose the appropriate authentication protocol tab below: To route your end-users directly to a bank/issuer authentication portal, you can specify the provider code in the `acr_values` parameter. For authentications with the Finnish Trust Network (FTN), you can specify the FTN provider with the `ftn_idp` parameter in the ACR values. The following example show how to route authentication to the Aktia Bank portal by customising the query parameter in your authorisation request: `acr_values=ftn_idp:fi-aktia,fi-pop,fi-op` To route your end-users directly to a bank/issuer authentication portal, you can specify the provider code the `RequestedAttribute` of your SAML 2.0 request. For example, for authentications with the Finnish Trust Network (FTN), you can specify the FTN provider with the `signicat:param:ftn_idp` attribute in your SAML request, as shown below: ```xml {4,10} fi-aktia ``` To serve a specific provider in an authentication session, you can use the `additionalParameters` field in the payload of the request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, for authentications with the Finnish Trust Network (FTN), you can customise your payload, as shown below: ```json {3} ... "additionalParameters": { "ftn_idp": "fi-aktia,fi-pop,fi-op" }, ... ``` For more examples and parameters, see the respective eID documentation: - [FTN](/identity-methods/ftn/attributes-reference.mdx#provider-scoping) - [iDIN](/identity-methods/idin/setup.mdx#issuer-bank-selection-screen) - [Smart-ID](/identity-methods/smart-id/setup/) ## eID scoping codes You can view the most common eIDs scoping codes in the table below. :::tip Scoping codes for your eIDs You can find scoping codes for your active eIDs in the **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn) page. ::: :::CustomTable{columnWidths="50% 50%"} | eID | Scoping codes | | ------------------------------------- | --------------------------- | | Auðkennisappið | `audkenni-app` | | BeID | `be-smartcard` | | buypass | `buypass` | | Czech Bank iD | `bankid-cz` | | DigiD | `digid` | | DigiD CombiConnect | `digid-combiconnect` | | eHerkenning | `eherkenning` | | Email OTP | `otp-email` | | eParaksts Mobile | `eparaksts-mobile` | | Estonian ID Card | `et-smartcard` | | Finnish eIDs (FTN) | `ftn` | | Finnish ID Card | `fi-smartcard` | | Freja eID | `freja` | | ID Austria | `idaustria` | | iDIN | `idin` | | ID-porten | `idporten` | | itsme® | `itsme` | | Latvian ID Card | `lv-smartcard` | | Lithuanian ID Card | `lt-smartcard` | | MitID | `mitid` | | MitID Business | `mitid-business` | | MitID Private to Business | `mitid-private-to-business` | | MobileID | `mobileid` | | mojeID | `mojeid-pl` | | Norwegian BankID | `nbid` | | Personalausweis | `npa` | | Polish ID Card | `pl-smartcard` | | Samleikin | `samleikin` | | Signicat IAM (SIAM) | `ownidp` | | SK Mobile-ID | `sk-mobileid` | | SK Smart-ID | `sk-smartid` | | Skilríki á korti | `is-smartcard` | | Skilríki á síma | `audkenni-mobileid` | | SMS OTP | `otp-sms` | | Sistema Pubblico di Identità Digitale (SPID) | `spid` | | Suomi.fi | `suomifi` | | Swedish BankID | `sbid` | | Swedish BankID Digital ID Card | `sbid-idcard` | | Simulator* | `simulator` | ::: \* The simulator is a tool for testing. Learn more in the [simulator documentation](/docs/eid-hub/e-ids/simulator/). --- ## Concepts You can learn about eID and Wallet Hub concepts in our guides. * [**IdP scoping**](/docs/eid-hub/concepts/idp-scoping): Control which eID your end-users authenticate with * [**Levels of Assurance**](/docs/eid-hub/concepts/levels-of-assurance): Set the degree of confidence with an eID * [**Localisation**](/docs/eid-hub/concepts/localisation): Language settings and internationalisation * [**Prefilling user information**](/docs/eid-hub/concepts/prefilling-information): Pre-populate login flows with user data * [**Single Sign-On (SSO)**](/docs/eid-hub/concepts/single-sign-on): Keep your users logged in across sessions * [**Subject**](/docs/eid-hub/concepts/subject): A unique identifier for the end-user --- ## Levels of Assurance The Level of Assurance (LoA) measures the degree of trust or confidence in the claimed identity of a person. It indicates how certain you can be about the claimed identity of your end-users when they use an eID to access your online services. This page provides conceptual information about the LoA supported by the eIDs in the eID and Wallet Hub, next to explanations and examples to help you configure the right level for your authorisation requests. ## How it works The Signicat eID and Wallet Hub supports four different Levels of Assurance (LoA): :::CustomTable | Level of Assurance | Code | Description | eIDAS | |:-------------------|:-------|:------------|:------| | *Unspecified* | `unspecified` | This level is undefined, and no information about the assurance level is available. The service providing the authentication cannot determine the level. For example, MobileID returns this level in its responses. | | | *Low* | `low` | This eIDAS level offers a moderate degree of confidence in the person's claimed identity. Single-factor authentication, such as a password, is sufficient for authentication use cases. During onboarding, this level might involve self-registration on a website, without any identity verification. | | | *Substantial* | `substantial` | This eIDAS level requires at least two-factor authentication. For example, a username and password in combination with a time-based token meet this requirement. For onboarding, end-user's identity information must be provided and verified. | | | *High* | `high` | This eIDAS level demands strong authentication measures to protect against duplication or tampering by potential attackers during authentication. For example, authentication using a smartcard, such as a national ID card, meets this requirement. For onboarding, an in-person registration process is mandatory. | | ::: When connecting to an eID, you can specify the LoA for authentication. ## Specify LoA in requests You determine the LoA for an authentication by specifying it as a parameter in your authorisation request. How to do that varies per authentication protocol. The table below shows how to request a specific (for example `high`) level of assurance with the different protocols supported by the eID and Wallet Hub: :::CustomTable | Protocol | Query parameter | |------------------------ |-----------------| | OpenID Connect (OIDC) | `acr_values=loa:high` | | Authentication REST API | `"requestedLoa":"high"` | | SAML 2.0 | ``   `high` `` | ::: :::note Default LoA If you don't specify any LoA in your authorisation request, the *minimum* LoA supported by the eID is used by default. For a complete list of values, refer to the [LoA supported by eIDs](#loa-supported-by-eids) section below. ::: ### Authorisation request examples How you pass the LoA in your requests varies per authentication protocol: To specify the LoA with OIDC, define `acr_values=loa:` in your authorisation request. For example, to ask for LoA `high`: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=loa:high ``` To specify the LoA with SAML 2.0, define the parameter in the Authentication Context Class Reference (`AuthnContextClassRef`) element in your `AuthnRequest` request. In the `AuthnContextClassRef`, you must pass the value of the **Name** field that you define in the mapping inside the [LoA contract](/docs/eid-hub/saml-2-0/saml-loa-contracts/). For example, to ask for LoA `high` you could build your request like this: ```xml {9-11} ENTITY_ID high ``` To specify the LoA with the Authentication REST API, define `requestedLoa` in the body of the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, to ask for LoA `high`: ```json {2} { "requestedLoa": "high", "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "allowedProviders": [...], "requestedAttributes": [...], "flow": "redirect", "sessionLifetime": 600, "returnUrl": "https://example.com/auth_callback", "requestDomain": "myapp.app.signicat.com" } ``` :::info Security validation The Signicat eID and Wallet Hub ensures that the same, or a higher, LoA is used for authentication. Learn more in the [Security validation](#security-validation) section. ::: ## View LoA in responses After an authentication is successful, the response you receive from the Signicat eID and Wallet Hub contains the level of assurance that the end-user authenticated with. To find out how the LoA is returned in the response, choose the appropriate authentication protocol below: After a successful authentication, you receive the LoA in the `acr` claim of the ID token, according to the [ID Token specifications](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). For example, an authentication performed with LoA High, returns `acr: "high"` in the payload of the ID Token. ```json {9} { "iss": "https://example.sandbox.signicat.com/auth/open", "sub": "pZsWJxH7eOfKa9Y3CR2mxTElnTAhu6o2ZWKOCpyOjWY=", "aud": "sandbox-vivid-blade-759", "nonce": "n-0S6_WzA2Mj", "iat": 1742917663, "exp": 1742918263, "auth_time": 1742917660, "acr": "high" } ``` After a successful authentication, you receive the LoA in the Authentication Context Class Reference (`AuthnContextClassRef`) inside the `AuthnStatement` of the SAML assertion. ```xml {4} high ``` The `AuthnContextClassRef` indicates the value of the **Name** field that you define in the mapping inside the [LoA contract](/docs/eid-hub/saml-2-0/saml-loa-contracts/). After a successful authentication, you receive the LoA in the `loa` property of the payload of the [Get session status](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) endpoint. For example, an authentication performed with LoA High, returns `"loa": "high"` in the payload. ```json {8} { "id": "911a3193...4afd058d25ff", "accountId": "a-sdge-XXXX", "authenticationUrl": "https://example.sandbox.signicat.dev/login", "status": "SUCCESS", "subject": {...}, "callbackUrls": {...}, "loa": "high" } ``` ## Filter eIDs by LoA When you have multiple eIDs active in your account and you start an authentication process, the eID and Wallet Hub authorisation server displays all the eIDs to your end-users in the eID selection screen. Typically, you control and restrict the selection of eIDs with [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx). When you specify a certain LoA in your request, only the eIDs that support the same level (or higher) will be displayed on the eID selection screen. For example, if you start an authentication request with LoA `substantial`, end-users can only choose among eIDs that support level `substantial` or `high`. ### Example Let's imagine a scenario where you have set up your integration to connect to the following eIDs: - SMS OTP (`low`) - Swedish BankID (`substantial`) - MitID (`low`, `substantial`, `high`). If your application starts an authentication requesting LoA `substantial`, the following happens: - SMS OTP is *not* displayed in the selection eID selection screen. LoA `low` is excluded. - Swedish BankID and MitID are available in the eID selection screen. - End-users can choose between Swedish BankID and MitID for authentication. - Authentications occur with a (minimum) Substantial level of assurance. ## Security validation If an eID authenticates end-users with LoA *lower* than requested by your application, the eID and Wallet Hub returns an error and the authentication fails. Before completing an authentication, the eID and Wallet Hub checks the validity of the LoA by applying the following algebraic inequality: `unspecified < low < substantial < high` :::info Example scenario If you send a request with LoA *Substantial* but the eID returns a response obtained with LoA *Low*, the Signicat eID and Wallet Hub terminates the authentication process and returns an error. ::: ### Validation rules During an authentication process, the eID and Wallet Hub checks that the LoA returned by an eID meets the following requirements: - If the LoA in the response is *lower* than what you requested in your authorisation request, the eID and Wallet Hub returns an error and the authentication process fails. - If the LoA in the response is *equal* or *higher* than what you requested in your authorisation request, the authentication process is valid and proceeds accordingly. **Exceptions** In SAML 2.0 connections with the `` element in the request: - If the LoA in the response is *different* (not equal) from what you requested, the eID and Wallet Hub returns an error and the authentication process fails. ## LoA supported by eIDs The table below shows the levels of assurance supported by each eID: :::CustomTable | **eID** | **Supported LoA** | | ------------------------------------- | ------------------------------------- | | Auðkennisappið | `high` | | .beID | `high` | | Buypass | `high` | | DigiD | `low`, `substantial`, `high` | | DigiD CombiConnect | `low`, `substantial`, `high` | | eHerkenning | `low`, `substantial`, `high` | | Email OTP | `low` | | eParaksts Mobile | `high` | | Estonian ID Card | `high` | | Finnish ID Card | `high` | | Freja eID | `low`, `substantial` | | FTN | `substantial` | | ID Austria | `substantial`, `high` | | iDIN | `substantial` | | ID-porten | `substantial`, `high` | | itsme® | `substantial`, `high` | | Latvian ID Card | `high` | | Lithuanian ID Card | `high` | | MitID | `low`, `substantial`, `high` | | MitID Business | `low`, `substantial`, `high` | | MitID Private to Business | `low`, `substantial`, `high` | | MobileID | `unspecified` | | mojeID | `low`, `substantial`, `high` | | Norwegian BankID | `substantial`, `high` | | Personalausweis | `high` | | Polish ID Card | `high` | | Samleikin | `substantial` | | SK Mobile-ID | `high` | | SK Smart-ID | `high` | | Skilríki á kortid | `high` | | Skilríki á síma | `high` | | SMS OTP | `low` | | Sistema Pubblico di Identità Digitale | `low`, `substantial`, `high` | | Swedish BankID | `substantial` | | Swedish BankID Digital ID Card | `substantial` | | Simulator | `unspecified`, `low`, `substantial`, `high` | ::: :::warning Important Some eIDs are not eIDAS-notified. In such cases, we map the response from the eID to the closest eIDAS equivalent. However, the process of obtaining an account for these eIDs may not fully comply with eIDAS requirements and the eID may not have been legally validated. ::: --- ## Localisation You can handle different languages within your applications with Signicat. This page describes how localisation is handled during an authentication flow. ## How it works The Signicat eID and Wallet Hub is localised to the languages shown in the table below. Note that English is the default (fallback) language. :::CustomTable{columnWidths="50% 50%"} | Language | Code | | :--------- | :-------- | | Danish | `da` | | Dutch | `nl` | | English (default) | `en` | | Estonian | `et` | | Finnish | `fi` | | French | `fr` | | German | `de` | | Greek | `el` | | Icelandic | `is` | | Italian | `it` | | Latvian | `lv` | | Lithuanian | `lt` | | Norwegian | `no` | | Polish | `pl` | | Swedish | `sv` | ::: :::note Language codes Languages are formatted as lowercase two-letter codes in ISO 639-1. For example, `en` or `no`. ::: ### Order of priority The language displayed on the graphical user interface (GUI) during an authentication flow depends on competing factors. The logic that determines what language is ultimately displayed to your end-users follows this order of priority: 1. **High**: The authorisation request (authentication URL) your application sends. 2. **Medium**: User browser settings (`Accept-Language` header). 3. **Low**: eID method language support. This relationship can also be represented by this formula: `ui_locales` / `language` (request) > `Accept-Language` (browser) > `en` (fallback) Note that English is always the fallback language. ### Authentication language When you start an authentication session and specify the language as a query parameter (for example, with `ui_locales` in OIDC), the following happens: 1. The service tries to show content in the language defined in your request. 2. If the language is not supported, then the service tries the language in the user browser settings. 3. If language in the user browser settings is also not supported, then localisation defaults to English. However, note that this may vary depending on the step in an authentication flow, as explained in the section below. ### Authentication steps An authentication session involves routing end-users through multiple screens and domains, which may affect localisation. A typical user journey involves the following steps: 1. The user wants to authenticate in your application/website. Here, you manage localisation on your side. 2. Optional. You direct the user to the eID selection screen where users can choose the eID method to authenticate with. Since this is part of the Signicat eID and Wallet Hub, you can control the language with query parameters in the authentication URL. :::note Optional Note that you may skip this step if you route the user directly to the eID portal with [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx), or when you only support one eID. ::: 3. The user is routed to the eID authentication portal. Localisation depends on the languages supported by the eID method. 4. The user is redirected back to your application/website. Similarly to step 1, you manage localisation on your side. You can learn more about how this works for different scenarios in the [Examples](#examples) section. :::tip Our recommendation We recommend that you let the end-users control the localisation settings, either automatically through their browser settings or by choosing supported languages in a dropdown list (if available). You should override the language only in specific cases. ::: ## How to edit the UI language When you want to overwrite the default language for the GUI, each authentication protocol requires that you adhere to the appropriate syntax. Below, you can find examples for each authentication protocol: To change the language of the GUI, you need to define the query string parameter `ui_locales` in your OIDC authorization request. For example, you can set the language to Greek (`ui_locales=el`) by passing the following in your request: ```bash {5} https:///auth/open/connect/authorize? &client_id=OIDC_CLIENT_ID &response_type=GRANT_TYPE_CODE &redirect_uri=REDIRECT_URI &ui_locales=el &scope=OIDC_SCOPES ``` To change the language of the GUI, you need to specify the language by using the `signicat:param:language` parameter in the SAML `AuthnRequest` Extensions. For example, you can set the language to Greek (`el`) by passing the following in your request: ```xml {4,10} el ``` To change the language of the GUI, you need to specify the `language` parameter in the payload of your request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, you can set the language to Greek (`"language": "el"`) by passing the following in your request: ```json {3} { "flow": "redirect", "language": "en", ... "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` ## Examples The following examples show how localisation works for different authentication scenarios. ### Supported language Below, you find examples of how authentication flows look like when both the eID and Wallet Hub and the eID method support the language configuration that you or your users require. #### Scenario 1: Default Imagine an authentication session where your application does not specify the language settings. :::info Authentication configuration - End-user browser language settings: *Norwegian* - Authentication URL language: *Not specified* - eID method: *Email OTP* \* \*Note that [Email OTP](/identity-methods/email-otp/about-email-otp/#language-support) supports Norwegian. ::: This will result in the following localisation in the authentication flow: 1. eID selection page: *Norwegian* 2. Email OTP page: *Norwegian* :::note Explanation In this scenario, the user browser settings determine the language for authentication because your request did not specify the language and Norwegian is supported by both the Signicat eID and Wallet Hub and Email OTP. ::: During authentication, your end-users will see with the following screens: #### Scenario 2: Specify language Imagine an authentication session where your application specifies the language settings. :::info Authentication configuration - End-user browser language settings: *English* - Authentication URL language: *Norwegian* (`ui_locales=no`) - Authentication method: *Email OTP* \* \*Note that [Email OTP](/identity-methods/email-otp/about-email-otp/#language-support) supports Norwegian. ::: This will result in the following localisation in the authentication flow: 1. eID selection page: *Norwegian* 2. Email OTP page: *Norwegian* :::note Explanation In this scenario, the language parameter you passed in your request determine the language for authentication. This is possible because Norwegian is supported by both the Signicat eID and Wallet Hub and Email OTP. ::: During authentication, your end-users will see the following screens: ### Unsupported language When you initiate an authentication session with a language that is supported by the Signicat eID but not supported by the eID method, the language might change during authentication to adjust to the eID method requirements. :::info Authentication configuration - End-user browser language settings: *French* - Authentication URL language: *French* (`ui_locales=fr`) - Authentication method: *Norwegian BankID* \* \*Note that Norwegian BankID only supports Norwegian and English. ::: This will result in the following localisation in the authentication flow: 1. eID selection page: *French* 2. Norwegian BankID: *Norwegian* During authentication, your end-users will see the following screens: :::note Unsupported language When the user browser setting language is not supported by the Signicat eID and Wallet Hub and you do not specify the language in the authorisation request, then localisation defaults to English. ::: --- ## Prefilling user information When your app already knows some information about a specific user, you can include such information as a hint in an authentication process. Prefilling allows you to pre-populate user data in the request to an eID provider. Typically, you reuse information that you have previously collected such as an email address, phone number or username. Passing data as a hint either displays the information to the user on screen or automatically skips a step in the authentication flow. Here are some advantages of prefilling user information: - Simplify and enhance the user experience within your app. - Offer more user-centric, intuitive, and efficient authentication flows. - Save the user time by pre-populating or skipping screens. - Ensure that an authentication request is tailored to a specific user associated with the data you pass to the identity provider. ## How it works Let's suppose that you already know the national identity number (NIN) of a user trying to authenticate with your app. For example, you collected the NIN in a previous step in the app or keep it stored in a database. A flow where you pre-fill user information would look like this: 1. You already know the NIN of the user. 2. The user wants to authenticate with your app. 3. You pass the NIN as a hint to the identity provider (eID). 4. The identity provider pre-populates the NIN on the login screen. 5. The user reviews the NIN and proceeds, instead of having to enter the value manually. :::note Security considerations When prefilling user information, developers must be aware of security risks and implement mitigation strategies to protect user data and application integrity. Learn more about it in the [Security considerations](#security-considerations) section below. ::: ## How to pre-fill user information To dynamically pre-fill user data, you specify the values as parameters in the authorisation request to the eID. How you pass data in your request varies per authentication protocol and provider. To view how to use prefilling with an authentication protocol, select the appropriate tab below: When using OpenID Connect (OIDC), you pass user data with the `login_hint` parameter. The format is a space-separated list of key-value pairs: `login_hint=key1:value1 key2:value2`. For example, use `login_hint=email:email%40example.com` to pass the email address of the end-user to the eID. Note how `%40` is the URL encoded version of the `@` sign. For example, to suggest the email address of the end-user in the Email OTP authentication screen your authorisation request might look like this: ```curl {9-10} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile%20idp-id &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=idp:email-otp &login_hint=email:email%40example.com ``` :::tip Format: URL encoding To ensure the property value is correctly interpreted in your OIDC authorisation request, you should format it using URL encoding. For example, use the URL encoded (percent encoding) `%2B447700900000` string to represent the `+44 7700900000` phone number. ::: Learn more about `login_hint` in the [login_hint](/docs/eid-hub/oidc/oidc-implementation.mdx#login_hint) documentation. You can pass prefilled information dynamically in your SAML 2.0 request. To include pre-filled attributes with `` dynamically in the `` itself, you embed attributes in an extension (``). For example, to suggest pre-fill the email address (`signicat:prefilled:email`) in the authentication screen, your request might looks like this: ```xml {10-18} ENTITY_ID email@example.com ``` When using the Signicat REST API, you pass user data in the `prefilledInput` field in the payload of the request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, to suggest the email address of the end-user in the authentication screen, your request might looks like this: ```json ... "prefilledInput": { "email": "email@example.com", }, ... ``` Learn more about `prefilledInput` in the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint of the REST API documentation. In the authentication flow, the end-user views the email address already pre-populated on the screen. For example, when prefilling the email address using [Signicat Email OTP](/identity-methods/email-otp/), the authentication screen looks like this: Email address dynamically pre-filled when the end-user authenticates with Email OTP Note that certain eIDs might instead skip one of the screens/steps in the flow. For example, if you pre-fill the NIN in your request to Norwegian BankID, the page where end-users typically enter their NIN is skipped by default. Instead, the end-user is directed to the next page in the flow, where they enter their password. This is to prevent that the NIN changes. For an overview of supported prefilling properties, see the next section below. ## Supported properties The table below shows what properties Signicat supports for prefilling user information in an authorisation request: :::CustomTable{columnWidths="50% 50%"} | **Name** | **Description** | | :------------------ | :------------------------------ | | `nin` | National identification number. | | `mobile` | Mobile phone number. | | `dateOfBirth` | Date of birth (YYYY-MM-DD). | | `email` | Email address. | | `username` | Username or User ID. | | `deviceID` | Mobile Device ID. | | `firstName` | First name. | | `lastName` | Last name. | | `bankAccountNumber` | Bank account number. | | `organisation` | Organisation name. | ::: **Note**: SAML 2.0 requires the following format: `signicat:prefilled:`. For example, `signicat:prefilled:email`. :::warning Coverage Note that certain identity providers support only a subset of the properties listed in the table above. For an overview of the values supported by an eID, see the [eIDs](/docs/eid-hub/e-ids/) documentation. ::: ## Security considerations A live implementation in production should adhere to the highest security standards. When setting up your app to pre-fill user information, keep the following security considerations in mind: ### Validate input and output Validating input consistency helps prevent potential security issues, such as user impersonation or man-in-the-middle attacks. When prefilling user information in the authorisation request, you must verify that the value you prefill matches the corresponding value returned by the eID in the response. For example, if you prefill `user@example.com` in the login hint, confirm that the same value is included in the response from the eID. If there is a mismatch between the prefilled value and the response value, your app should reject the session and prompt the user to authenticate again. Do not rely only on the prefilled value to identify a user. ### Use signed requests and Pushed Authorization Requests (PAR) When setting up your app for prefilling user information with OIDC, the following measures help you mitigate any security risks: - [Encrypted or signed requests](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests.mdx): ensures the integrity and authenticity of the `login_hint` and other parameters. - [Pushed Authorization Requests (PAR)](/docs/eid-hub/oidc/advanced-security/pushed-authorization-requests-par.mdx): transmits parameters through a backchannel, protecting them from exposure in the browser or query strings. ## Other resources Below you find examples of prefilling user information: - [Example with MobileID](/identity-methods/mobileid/integration-guides/oidc/ciba-flow/implementation.mdx) - [Example with Swedish BankID](/identity-methods/sbid/integration-guide/oidc-sbid/#login_hint-prefill-user-information) - [Example with SMS OTP](/identity-methods/sms-otp/setup/oidc/#prefill-user-information) - [Example with Email OTP](/identity-methods/email-otp/setup/oidc/#prefill-user-information) - [Pre-filling with SAML 2.0](/docs/eid-hub/saml-2-0/saml-requested-attributes/#prefilled-information) --- ## Single Sign-On Single Sign-On (SSO) allows you to keep users logged in across multiple services over time. When you enable SSO, your users only need to log in the first time they access your app without having to authenticate again when they come back later. :::warning Limited support Currently, we only support SSO at the eID and Wallet Hub level for SAML 2.0. Therefore, the information on this guide only applies to SAML 2.0. We also support SSO at the OIDC level. Learn more about SSO for OIDC in the [OIDC implementation](/docs/eid-hub/oidc/oidc-implementation.mdx#single-sign-on-sso) guide. ::: ## How SSO works The eID and Wallet Hub SSO stores a token (session cookie) in the browser of the user to identify them when they return to authenticate with your application. The token does not contain any personal identifiable information. Based on the token and the parameters in the authentication request (for example, LoA and attributes), the eID and Wallet Hub checks whether the SSO is still applicable and handles the authentication appropriately. When you activate SSO in the eID and Wallet Hub, Signicat keeps the login response for a user session after a successful login transaction. The next time (within the same session) a new login transaction starts, the end user will not have to log in again. Instead, the same response that Signicat stored in the first login transaction will be automatically returned to your application. The response will contain the same subject identifier and any other attribute you requested previously. :::info SSO lifetime The SSO process happens within the context of a user session. If the user closes the browser, SSO will terminate and the user must re-authenticate. Technically, this means that the SSO is non-persistent. ::: ### Levels of SSO Note that SSO may occur at different levels. We distinguish between the following levels: 1. eID and Wallet Hub (described on this page) 2. OIDC server (see the [OIDC documentation](/docs/eid-hub/oidc/oidc-implementation.mdx#single-sign-on-sso)) 3. IdP or eID (depends on the identity provider) When integrating with an eID using the Signicat eID and Wallet Hub, it is important to consider the interactions that might occur between different SSO levels. ### Technical considerations Note that SSO does not work when: - The IP of the end-user changes from one authentication to the next. - The level of assurance (LoA) requested in a subsequent request is higher than the LoA used in the initial login. - Your account configuration changes between sessions so that the authentication provider is no longer active in your account. - You scope an eID (see [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx)) differently than in the initial request. - You send an OIDC authentication request with `prompt=login`. - You send a SAML authentication request with `forceAuthn=true`. - You connect using the Signicat Authentication REST API, which does not support SSO. In any of the above scenarios, the end-user must re-authenticate. ## Enabling SSO You can enable SSO at the eID and Wallet Hub level in the Signicat Dashboard. To do this: 1. Log in to the [Dashboard](https://dashboard.signicat.com). 2. Navigate to **Products** > **eID and Wallet Hub** > [**Settings**](https://dashboard.signicat.com/bca/settings/edit). 3. Select **Enabled** in the **SSO settings** dropdown. SSO session management settings 4. Configure the SSO-related settings: :::CustomTable{columnWidths="25% 50% 25%"} | Name | Descriptions | Default value | |-------------------|---------------------|----------------------------------| | Session duration | The length of time before the SSO session expires. This is the time after which the user must re-authenticate. | 30 | | Unit | The time unit (minutes or hours). | Minutes | | Use rolling validity | Tick this checkbox to extend the remaining session duration every time the user log in. For example, if the remaining session duration is 10 minutes and the user logs in again, then the total session time will equal 10 minutes plus the value of *Maximum session duration*. | Off | | Maximum session duration | Time to add to the overall session duration every time a user logs in. | 30 | | Unit | The time unit (minutes or hours). | Minutes | ::: 5. Scroll at the bottom of the page and select **Save** to persist the changes. After you enable SSO, these settings apply to all future authentication transactions started using this account. :::note SSO configuration applies at the account level When you enable SSO in the Signicat Dashboard, SSO is configured at the account level. {/* TODO: update to all protocols when supported */} All authentications transactions with SAML 2.0 for this account will enforce SSO, by default. ::: ## Skipping SSO You can bypass the SSO configuration in the Dashboard by providing specific parameters in an authentication request. How to do this varies per authentication protocol. :::note Skipping SSO applies to all levels When bypassing SSO in your authentication request, SSO is skipped across *all* levels. Therefore, end-users must always re-authenticate, regardless of any other SSO level configuration. ::: When sending an authentication request with OIDC, the `prompt` attribute allows you to ignore any existing session and prompt the user to re-authenticate. To do this, set the `prompt=login` parameter in your authentication request, as shown below: ```curl {9} title="OIDC Authentication request with prompt=login" https://example.sandbox.signicat.com/auth/open/connect/authorize? client_id=sandbox-vivid-blade-759 &response_type=code &redirect_uri=https://oauth.tools/callback/code &state=1734687023840-WGZ &scope=openid%20profile%20nin &code_challenge=7aEnwazbpKXHjOYbISsHWbtAWn33fE9cgDpS0y4-0UM &code_challenge_method=S256 &prompt=login ``` The above request bypasses SSO and prompts the user to re-authenticate. Note that SSO is still enabled for future requests *without* `prompt=login`. Skipping SSO is transient and different from forcing logout. When sending an authentication request with SAML 2.0, the `ForceAuthn` attribute allows you to ignore any existing session and prompt the user to re-authenticate. To do this, set the `ForceAuthn="true"` attribute in the `` element of your SAML request, as shown below: ```xml ENTITY_ID XML_SIGNATURE ``` The above request bypasses SSO thus prompting the end-user to re-authenticate. Note that SSO is still enabled for future requests *without* `ForceAuthn="true"`. Skipping SSO is transient and different from forcing logout. :::warning Not supported The Signicat Authentication REST API does *not* support SSO, by design. That means that end-users are required to authenticate every time they access or return to your services. ::: {/* TODO: needs more info: If you pass as additional parameter `skip_sso` it will skip the eID and Wallet Hub level SSO, but not necessarily the SSO at the IdP level. */} ## Other resources - [SSO at the OIDC server](/docs/eid-hub/oidc/oidc-implementation.mdx#single-sign-on-sso) --- ## Subject The subject uniquely identifies the end-user that performed an authentication transaction. It allows you to correlate the end-user activity across multiple authentication sessions. For different protocols, we return the subject using the following attributes/claims in the response: :::CustomTable{columnWidths="50% 50%"} | Protocol | Attribute/claim | |------------------------ |--------------| | OIDC | `sub` | | Authentication REST API | `subject.id` | | SAML 2.0 | `NameID` | ::: :::note The subject is always hashed After an authentication transaction, you receive the subject *always* in **hashed** form. Hashing converts the subject into a fixed-length, irreversible value that ensures consistency and privacy-sensitive identification of an individual without exposing their personal information. ::: :::info How to receive the raw subject You can also request the raw (unhashed) subject. To do this, you need to specify an additional query parameter in your request, as explained in the [How to receive the raw subject](#how-to-receive-the-raw-subject) section. ::: ## Hashing algorithm We generate the hashed subject using the same hashing algorithm for all protocols with the following function: ```curl Hashed_Subject = Replace(Base64(Sha256(output_of_proprietary_algorithm))) ``` Here is a step-by-step overview: - **Sha256**: The hashing algorithm. Input bytes are created using the `output_of_proprietary_algorithm`, which is comprised of the following input elements: - `idp`: Signicat-specific code to indicate the eID used for authentication. For example, `nbid` for Norwegian BankID. - `idpId`: Raw subject, as provided by the eID (identity provider). Learn more in the [Raw subject](#raw-subject-and-the-idpid-attribute) section. - `organizationId`: Uniquer identifier of your organisation, as registered in the Signicat Dashboard. - **Base64**: Applies Base64 encoding to the hashed input string from the previous step. - **Replace**: Replaces all `+` and `/` characters with `-`. ## Subject types eIDs may return different subject values for the same end-user, thus making it difficult to track the end-user across authentication sessions. To ensure integrity, we distinguish between two types of subject: - **Persistent**: An eID always supplies the exact same value to identify a specific end-user across sessions. - **Transient**: The subject varies across authentication sessions. For example, Finnish Trust Network (FTN) provides a different subject identifier for each new session. Below you can find out how we process each subject type. ## Raw subject and the idpId attribute We process the raw subject, referred to as `idpId`, from the response we receive from the eID (third-party). The raw subject output varies for each eID, depending on availability and the type of subject. We apply the following logic to generate the `idpId` attribute that we send you: - If an eID returns a **Persistent** subject identifier to Signicat, we use this value as the `idpId` to generate the hashed subject. - If an eID returns a **Transient** subject or does not return any subject identifier to Signicat, we try to generate a persistent hashed subject from another attribute. The criteria to choose an attribute is that it must be unique and consistent to identify a specific end-user. For example, we may select the National Identity Number (`nin`) as the `idpId`. For details on how we process transient (or missing) raw subjects for an eID, refer to the specific [eID](/docs/eid-hub/e-ids/) documentation. ### How to receive the raw subject After an authentication transaction, you always receive the hashed subject. To also receive the *raw subject*, you need to request it additionally by specifying a query parameter (`idpId`) in your request. How you format the parameter varies per authentication protocol. The table below shows how to request the raw subject through the `idpId` parameter for the different protocols: :::CustomTable{columnWidths="50% 50%"} | Protocol | Parameter (request) | |------------------------ |---------------------| | OIDC | `scope=idp-id` | | Authentication REST API | `"requestedAttributes":["idpId"]` | | SAML 2.0 | `` | ::: After the authentication transaction, you will find the raw subject in the payload of the response. These are the attributes in the response per protocol: :::CustomTable{columnWidths="50% 50%"} | Protocol | Attribute (response) | |------------------------ |-----------------| | OIDC | `idp_id` | | Authentication REST API | `subject.idpId` | | SAML 2.0 | `idpId` | ::: --- ## Auth0 integration guide (with OIDC) Signicat's electronic identities ([eIDs](/docs/dashboard/glossary.mdx#eids)) can be integrated in an Auth0 tenant to authenticate end-users through the Auth0 platform. - **Auth0** provides an Identity Access Management (IAM) platform that helps companies manage and secure user authentication into applications. - **Signicat** provides an identity hub with many eIDs, suitable for onboarding new users and authenticating recurring users. A list of supported providers is available in the [eIDs](/docs/eid-hub/e-ids/) section. Auth0 customers can easily add Signicat services with simple configuration steps, rather than spending time and effort on development capacity. Using Auth0's Custom Social Connections, you can integrate your tenant with any OAuth 2.0 provider. For example, you can connect to the eIDs offered by Signicat, such as Norwegian BankID. Follow the instructions on this page to learn how to integrate Signicat's identity hub into your Auth0 tenant using a [Custom Social Connection](https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/oauth2) supported by [OpenID Connect (OIDC)](https://openid.net/connect/). ## Supported features Signicat supports an identity hub that is able to provide many different eIDs through a single OIDC integration. This allows you to easily add any eID to your application in the Auth0 tenant. Since many different eIDs require specific configurations, the generic eID and Wallet Hub allows for the usage of scopes during the authorisation flow. You can find more information about these scopes in the documentation specific for each [identity method](/docs/eid-hub/e-ids/). ## Requirements The first step is to make sure you have both accounts set up correctly. Here is what you need: - Access to the [Auth0 Dashboard](https://manage.auth0.com/#). - Access to the [Signicat Dashboard](https://dashboard.signicat.com). If you already have access to both Dashboards, skip to the [configuration steps](#configuration-steps) section below. ### Auth0 registration To connect Signicat's eIDs with Auth0, you need access to the [Auth0 Dashboard](https://manage.auth0.com/#). If you don't have an Auth0 account, sign up at [Auth0.com](https://auth0.com/signup). After registration, Auth0 will provide you with an admin dashboard where you can manage your Auth0 tenant. {/*Follow the instructions on the Auth0 website to configure your Auth0 Dashboard account.*/} ### Signicat registration This section explains how to get started with the [Signicat Dashboard](https://dashboard.signicat.com). If you already have an account with Signicat, you can skip to the [configuration steps](#configuration-steps) section below. To integrate with Signicat services through Auth0, you need to sign up to Signicat. The Signicat Dashboard is where you manage all aspects of your Signicat subscription and configuration. You can sign up for free by following the steps in our [Get started](/docs/) guide. :::note Sandbox and production accounts We recommend you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ## Configuration steps This section provides an overview of all the configuration steps required to connect Signicat eIDs, as Identity Providers, through your Auth0 tenant. ### Step 1. Create an OIDC client To establish a connection between the Auth0 tenant and Signicat eIDs you need to use an authentication protocol, like OpenID Connect (OIDC). When adding Signicat as an OAuth 2.0 provider in the Auth0 tenant, you need to register a pair of OIDC client credentials (a Client ID and a Client Secret). To create a new OIDC client, open the Signicat Dashboard and navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) and click **Create Client**. Below a summary and definitions of the values to fill in the form: - **Client name**: the name of the client, shown to end-users on consent screens. - **Primary Grant Type**: the grant type you want to use with this client. We strongly recommend **AuthorizationCode**. For further information about the different grant types, refer to the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#Authentication) and the [OAuth 2.0 specification](https://oauth.net/2/grant-types/). - **Redirect URI**: the redirection URI to which the response will be sent at the end of an OIDC flow. It must be HTTPS and an absolute URI. :::tip Redirect URI When configuring the OIDC client, enter the redirect URI with format `https://{yourDomain}/login/callback`, where `yourDomain` is the domain of your Auth0 tenant. ::: - **Scope**: The scopes will determine which attributes are returned as output of the OIDC flow, and the full set depends on the chosen eID. Different eIDs require different scopes and return different values. `openid` is mandatory and `profile` is necessary in most cases. Depending on the desired eID, you might need to include other scopes (such as `nin`, which gives access to national identity number for some eIDs). You can find the details for each eID in the [Identity Methods](/docs/eid-hub/e-ids/) page. For example, see the list of [scopes and claims for Norwegian BankID](/identity-methods/nbid/attributes-reference.mdx#oidc-scopes-and-claims). :::note Note You can see the definition of `profile` and other predefined scopes in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). As for `nin`, this scope requests access to the end-user's national identification number. ::: #### Create a client secret After you create a client, you can add a secret associated to that client. Click **Add secret** and enter a name to generate a secret. You can view and add more secrets in the "Secrets" tab of your OIDC client. :::warning Important Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one. ::: Once you have set up the Signicat client credentials for the OIDC connection, you're ready to proceed with [Step 2. Add an eID](#step-2-add-an-eid) and add Signicat's eIDs to your account. ### Step 2. Add an eID This guide shows you how to set up [BankID (Norway)](/identity-methods/nbid/) in your Signicat account. You can always add more eIDs. Note that certain eIDs require additional configuration and sign agreements with either Signicat or the identity providers to obtain the needed access, in production. The eIDs associated to your account will be accessible via the Auth0 tenant, once you register your Signicat OIDC client on the Auth0 Dashboard. You can find a list of supported eIDs per country [here](/docs/eid-hub/e-ids/). #### Add BankID (Norway) BankID is an electronic identity scheme in Norway that can be used for identity verification, authentication and electronic signing of documents. To set up BankID: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com/). 2. Navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 3. Click **Add new**. 4. Choose "Norwegian BankID" from the list of supported eIDs. 5. Click **Save**. Norwegian BankID should now appear in the list of available eIDs with the status set to "Active". Learn more about BankID features and advanced configuration options in the dedicated section [here](/identity-methods/nbid/). ### Step 3. Create a custom social connection On the Auth0 Dashboard you can add any OAuth 2.0 provider using a Custom Social Connection. The purpose of this step is to configure the Signicat OIDC client in the Auth0 tenant. The information in this section is specific to configuring a connection with Signicat. You can learn more about general configuration of Custom Social Connections in the [Auth0 documentation](https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/oauth2). #### Create a connection To create a new Custom Social Connection, navigate to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social), click **Create Connection**, scroll to the bottom of the list and click **Create Custom**. To configure a connection, fill in the form with the following information: - **Name**: the name of the connection. The name cannot be changed, must start and end with an alphanumeric character, and can only contain alphanumeric characters and dashes. - **Authorization URL**: `https:///auth/open/connect/authorize`, where the `` is the domain defined in the **Dashboard** > [**Domains**](https://dashboard.signicat.com/domains) page. - **Token URL**: URL used to exchange the received authorization code for access tokens and, if requested, ID tokens. Enter `https:///auth/open/connect/token`. - **Scope**: the OIDC scopes to send with the authorisation request. Separate multiple scopes with spaces. You can explore more scopes for BankID in the [Scopes and claims mapping for OIDC](/identity-methods/nbid/attributes-reference.mdx#oidc-scopes-and-claims). :::warning Important The scopes you enter here must match the scopes you defined for the OIDC client in the Signicat Dashboard. ::: - **Client ID**: the Client ID associated to your OIDC client. - **Client Secret**: the client secret associated to your OIDC client. - **Fetch User Profile Script**: Node.js script used to call a UserInfo URL with the provided access token and retrieve claims data. Learn how to write a script in the [Fetch User Profile Script section](#fetch-user-profile-script) below. Custom Social Connection form fields ##### Fetch User Profile Script The `UserInfo` endpoint is part of the [OpenID Connect standard (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) and is designed to return claims about the authenticated user. To obtain the data of the requested claims from the `UserInfo` endpoint, you can define a custom code snippet in Node.js. Here is an example script: :::details Expand example ```js function(accessToken, ctx, callback) { const profile = {}; request.get( { url: 'https:///auth/open/connect/userinfo', headers: { 'Authorization': 'Bearer ' + accessToken, } }, (err, resp, body) => { if (err) { return callback(err); } if (resp.statusCode !== 200) { return callback(new Error(body)); } let bodyParsed; try { bodyParsed = JSON.parse(body); } catch (jsonError) { return callback(new Error(body)); } const profile = { user_id: bodyParsed.sub, name: bodyParsed.name, given_name: bodyParsed.given_name, family_name: bodyParsed.family_name }; callback(null, profile); } ); } ``` ::: Here are a few details: - `url`: is the **UserInfo** URL of your Signicat domain. Substitute `` with the domain associated to your account and defined in the **Dashboard** > [**Domains**](https://dashboard.signicat.com/domains) page. - `const profile` determines the attributes returned from the information the end-user consents to (if necessary) during authentication. - `bodyParsed` is the parsed JSON of the response body sent from the eID. You can access attributes from the **UserInfo** response with the values in the format `bodyParsed.`, such as `bodyParsed.given_name`. Using the above script in a test connection would return the following data: :::details Expand example ```json { ... "sub": "oauth2|Signicat-connection|-BoDH7BDacLNL4ut********44m98r3NDa9uTRE=", "family_name": "Williams", "given_name": "Ellie", "nickname": "", "name": "", "picture": "https://cdn.auth0.com/avatars/default.png", ... } ``` ::: You can manage your users from [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users). This is where you can view the Raw JSON data returned by the end-user login flow. ##### Advanced Fetch User Profile Script You can expand the profile to include more attributes. For example, you can retrieve `birthdate` and `nin` (national identity number) information by adding more fields like: :::details Expand example ```js {7-8} // omitted for brevity const profile = { user_id: bodyParsed.sub, name: bodyParsed.given_name + ' ' + bodyParsed.family_name, given_name: bodyParsed.given_name, family_name: bodyParsed.family_name, birthdate: bodyParsed.birthdate, nin: bodyParsed.nin }; // omitted for brevity ``` ::: In this case, the user profile data received is: :::details Expand example ```json {4,9} { ... "sub": "oauth2|Signicat-connection|-BoDH7BD8fLNL4ut******44m98r3NDa9uTRE=", "birthdate": "1908-09-29", "family_name": "Williams", "given_name": "Ellie", "name": "Ellie Williams", "nickname": "Ellie Williams", "nin": "01100844350", "picture": "https://cdn.auth0.com/avatars/default.png", ... } ``` ::: You can customise the attributes of the profile returned by the identity provider. The number of attributes you can retrieve depends on a few factors, such as the identity provider, the user consent, the configuration of your Auth0 tenant, and (importantly) the scopes you configure with your OIDC client. You can explore the Signicat scopes (and corresponding claims) for Norwegian BankID in the [Scopes and claims mapping for OIDC](/identity-methods/nbid/attributes-reference.mdx#oidc-scopes-and-claims). #### Add the Application Once you create a custom connection, you will see the **Applications** view. Here, you can enable and disable applications for which you would like the connection to appear. If you don't have any applications in your account, please [create an Application](https://auth0.com/docs/get-started/auth0-overview/create-applications). Click on the toggle button to enable at least one Application. For example, you can link the connection to a Single Page Application, or any other application of your choice. You are all set! You can now test the connection and authenticate with a test user for Norwegian BankID before going live in production. ### Step 4. Test the connection To test the configured flow, you can either add the OIDC flow to an frontend application or try the connection directly from the Auth0 tenant. To test the OIDC flow from the Auth0 tenant, navigate to the [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social), click the Social Connection you created and click **Try connection** to start the user authentication flow. Choose **Norwegian BankID** and sign in with a [test user](/identity-methods/nbid/test.mdx#test-credentials) as follows: :::CustomTable{columnWidths="33% 33% 33%"} | National identity number | One time password | Password | | :----------------------- | :---------------- | :--------- | | `01100844350` | `otp` | `qwer1234` | ::: Here is how a user flow looks like (with BankID app): ### Step 5. Go live To implement the flow in production, set up the Signicat OIDC client from a production account in the Signicat Dashboard. Choose a production account in the [**Organisation management**](https://dashboard.signicat.com/org-mgmt/) page in the Signicat Dashboard and repeat the steps in this guide. :::warning Agreements required Note that while the technical implementation steps stay the same, you must sign an agreement with Signicat to start accepting authentication from real legal persons. To sign an agreement, log into the [Signicat Dashboard](https://dashboard.signicat.com/) and click 'Talk to sales' in the banner at the top of the page. ::: Also, take a look at the [Auth0 pre-deployment checks](https://auth0.com/docs/deploy-monitor/pre-deployment-checks) to make sure the entire setup is ready to be launched in a production environment! If you have any questions about the integration, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Connectors Integrate with Signicat eID and Wallet Hub from various third-party authentication providers. * [**Auth0**](/docs/eid-hub/connectors/auth0-integration): Integrate Signicat eID and Wallet Hub with Auth0 using OpenID Connect --- ## Demo The eID and Wallet Hub demos allows you to explore the user experience of electronic identities (eIDs) firsthand, with no setup required. Demos are tools designed for you to explore the eID and Wallet Hub and understand the steps in a typical user journey with a specific eID. To try out a demo with an eID, visit the eID and Wallet Hub demos at: [**eID and Wallet Hub demos**](https://demo.signicat.com/?filters=or(product:eID-Hub,product:eID-and-Wallet-Hub)) :::tip Test credentials Many eIDs provide test credentials for authentication. We provide test credentials in the demo. To view more test credentials and explore other options for testing an eID, visit the specific [eID documentation](/docs/eid-hub/e-ids/index.mdx). ::: We recommend trying out the demo when: - You are interested in identity proofing, user authentication, and electronic signing with eIDs but don't know where to start. - You are just getting started with Signicat eID and Wallet Hub. - You want to familiarise yourself with an eID *before* investing your time for setup. :::note Testing only The demo eIDs are for testing purposes only and do not perform any real authentication. ::: ## Troubleshooting and support If you encounter any issues with the demo site: 1. Ensure that your browser is updated to the latest version. 2. Verify that your test credentials are correct. If the issue persists, contact the Signicat support team by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ## Next steps When you are ready to get started with the eID and Wallet Hub, follow the steps in the [Quick start guide](/docs/eid-hub/quick-start/). --- ## Add eIDs The first step when you integrate with the eID and Wallet Hub is to add, configure and activate an eID in your account in the Signicat Dashboard. ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::note Domains and eIDs For the scope of this guide, you can use a standard Signicat domain. However, note that certain eIDs may require additional security measures, such as the use of digital SSL certificates and custom domains. You can find more details in the specific documentation for the [eID](/docs/eid-hub/e-ids/). ::: ## How to add an eID To add an eID to your Signicat account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. :::note Additional configuration Certain eIDs may require additional configuration or support from our onboarding team. For more information about a particular eID, navigate to the [eID](/docs/eid-hub/e-ids/) page or contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Testing an eID After you have added and configured the eID, you can run a test in the Dashboard, as explained in the [Test eIDs](/docs/eid-hub/e-ids/test-eids/) guide. If your eID requires additional configurations, you can use the Simulator. Learn more about this feature in the [Simulator](/docs/eid-hub/e-ids/simulator/) documentation. ## Next steps Typically, the next step in your integration is to set up a connection between your application and the eID and Wallet Hub using one of the supported authentication protocols: * [**OpenID Connect (OIDC)**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains. * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users. --- ## eIDs Integrate digital identities and third-party information sources through Signicat eID and Wallet Hub. Follow the links below to read about the eID, access to get started guides, use cases, and more. ## Guides Explore our guides to set up and test an eID. * [**Add eIDs**](/docs/eid-hub/e-ids/add-eids): Activate an eID in the Signicat Dashboard * [**Test eIDs**](/docs/eid-hub/e-ids/test-eids): Start testing and understand the user journey * [**Simulator**](/docs/eid-hub/e-ids/simulator): Customise your testing environment with the simulator --- ## Simulator The Simulator is a tool in the eID and Wallet Hub to test an authentication process without the need to add or activate any eID in your account. The Simulator acts as an identity provider simulator to return sample responses that help you understand the user attributes that apply to a specific eID. We recommend using the Simulator when: - You want to test an eID *before* it becomes active in your account; for example, when you are waiting for a certificate. - There exists no test credentials for a given eID. - You want a flexible solution to customise the user attributes returned from authentication. - You want to test a connection with an authentication protocol without depending on a specific eID. :::note Notes - The Simulator works both with and without using a connection with an authentication protocol. - The Simulator is only available for use in a sandbox account. ::: ## How it works The Simulator is a flexible tool that lets you test and prepare for your integration in a self-contained environment. When using the Simulator, you mock an authentication process without connecting directly to an eID. Nonetheless, you can customise and review the user attributes that you would normally receive after a successful authentication. You don't need any test credentials or to activate any eID in your account. When you add the Simulator to your sandbox account, it becomes available for testing like any other eID: Simulator available as an eID in a sandbox account. :::note Data quality The Simulator provides only a limited sample of user attributes. Use it as a testing tool to support your development, rather than a definitive source of truth. ::: ## Get started To use the Simulator, you must first add it in your Signicat account. :::note Which eIDs does the Simulator support? The Simulator is currently available for a portion of the eIDs in the eID and Wallet Hub. We are in the process of adding support for more eIDs, and will eventually roll out support for all. ::: ### Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::note Domains and eIDs For the scope of this guide, you can use a standard Signicat domain. However, note that certain eIDs may require additional security measures, such as the use of digital SSL certificates and custom domains. You can find more details in the specific documentation for the [eID](/docs/eid-hub/e-ids/). ::: ### Add the Simulator Before you can start testing, add the Simulator by following these steps: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **+ Add new** in the top-right corner. 3. Select **Simulator** from the list of supported eIDs. 4. On the Simulator configuration page, set the following: - **Name**: The name of the Simulator (required). - **Include only when scoped**: If ticked, the Simulator is available for authentication only when you pass `Simulator` in the query parameter of your request. Scoping varies per authentication protocol. Learn more in the [Scoping the Simulator](#scoping-the-simulator) section (optional). - **Select attribute filter**: Allows you to use an attribute filter (optional). - **Response attribute mappings**: Maps attributes to keys that you define (optional). 5. Select **Add** to activate the Simulator. Here is how the configuration page looks like: How to configure the Simulator. Now, you can choose the Simulator as an eID for testing. ## Start testing You can run tests using the Simulator in three ways: 1. [Test with eIDs](#test-with-eids) 2. [Test with custom provider](#test-with-custom-provider) 3. [Test protocol connections](#test-protocol-connections) ### Test with eIDs Imagine a scenario where you want to implement Swedish BankID in your application. Before starting the integration, you want to test it but you don't have any credentials. Instead, you can test Swedish BankID with the Simulator, by doing this: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right. 3. Choose the **Simulator** from the list of available providers. The name of the Simulator depends on your configuration. 4. In the next step, choose **Swedish BankID**. 5. Optional. Edit the data to suit your needs. Then, select **Send** to send the request. 6. Review the user data attributes in the response. Here is how the steps look like in the Dashboard: ### Test with custom provider To test an authentication process without any particular eID, you can choose a custom provider. To do this: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right. 3. Choose the **Simulator** from the list of available providers. The name of the Simulator depends on your configuration. 4. In the next step, choose **Custom**. 5. Edit the data according to your needs. Then, select **Send** to send the request. 6. Review the user data attributes in the response. ### Test protocol connections A notable scenario to use the Simulator is when you are building the integration and want to test a connection after you set up an authentication protocol. We support [OpenID Connect (OIDC)](/docs/eid-hub/oidc/), [SAML 2.0](/docs/eid-hub/saml-2-0) and the Signicat [Authentication REST API](/docs/eid-hub/authentication-api/). When you navigate to the authorisation URL you built with an authentication protocol, you can choose the Simulator as an identity provider in the provider selection screen. For example, an authorisation (URL) request using OIDC might look like this: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile &state= &code_challenge=ABC123 &code_challenge_method=S256 ``` To skip the selection screen and route directly to the Simulator UI, you can [scope the Simulator](#scoping-the-simulator). #### Scoping the Simulator To bypass the selection screen with the different protocols, use the following query parameters in your authorisation request: :::CustomTable | Protocol | Query parameter | |------------------------ |-----------------| | OIDC | `acr_values=idp:simulator` | | Authentication REST API | `"allowedProviders": ["simulator"]` | | SAML 2.0 | ``  ``    ``  ```` | ::: :::note Note Scoping also works when you enable the **Include only when scoped** setting, as explained in the [Add the Simulator](#add-the-simulator) section above. ::: #### Scoping request examples To automatically test the Simulator with OIDC, define `acr_values=idp:simulator` in your authorisation request: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope=openid%20profile &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=idp:simulator ``` To automatically test the Simulator with SAML 2.0, define `ProviderID="simulator"` in your `AuthnRequest` request: ```xml {8-12} ENTITY_ID ``` To automatically test the Simulator with the Authentication REST API, define `allowedProviders` in the body of the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint, as shown below: ```json ... "allowedProviders": [ "simulator", ], ... ``` --- ## Test an eID You can test an authentication process with any eID directly from the Signicat Dashboard. Testing allows you to better understand the user experience with an eID and helps you prepare for the integration. We recommend using the solution described on this page when: - You have already added eID in your Signicat account. To learn how to add an eID, see [Add eIDs](/docs/eid-hub/e-ids/add-eids.mdx). - You want to test an eID *before* connecting with an authentication protocol, such as OIDC, SAML 2.0 or the Signicat Authentication REST API. - You have access to test credentials for the eID. This guide explains how to get test users. When the scenario above doesn't meet your requirements, consider using the [Simulator](/docs/eid-hub/e-ids/simulator.mdx). ## How to test an eID in the Dashboard :::info Before you begin Before you begin, make sure to follow the steps to [Add eIDs](/docs/eid-hub/e-ids/add-eids.mdx) in the Dashboard. ::: To test an authentication flow in the Dashboard, do the following: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right. 3. Optional: If you've activated more than one eIDs, choose the eID from the list of available providers. 4. Follow the steps on the provider site using your test credentials. 5. Review the user data attributes returned by the eID. When you complete a test authentication, the test site shows you examples of responses containing the user attributes. ## Test example To quickly run a test with an eID, add the Signicat Email OTP to your account, following the steps in the [Add eIDs](/docs/eid-hub/e-ids/add-eids.mdx) guide. Once you have added the Email OTP method, you can test it in just a few clicks. To do this: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right. 3. Optional: Choose **Email OTP** from the list of available providers. Applies only if you have more than one eID active in your account. 4. In the Email OTP screen, enter your email address. Then, select **Next**. 5. In your email inbox, open the email from Signicat and copy the one-time password (OTP). 6. Navigate back to the Email OTP authentication tab and enter the OTP. 7. Select **Verify** to authenticate. Here is what the user journey would look like: ## Test user credentials Many eIDs provide test credentials that allow you to mock an authentication process. Navigate to the specific [eID](/docs/eid-hub/e-ids/index.mdx) documentation to find test information. ## Next steps Typically, the next step in your integration is to set up a connection between your application and the eID and Wallet Hub using one of the supported authentication protocols: * [**OIDC**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains. * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users. --- ## EU Digital Identity Wallet # Identity wallets Signicat is fully committed to supporting the upcoming **EU Digital Identity Wallet** (EUDI Wallet) project. The EUDI Wallet is a secure, voluntary mobile application that enables EU citizens, residents, and businesses to store, share, and manage digital identity credentials and documents, such as driver's licences, diplomas, and bank accounts, across all EU member states. Our eID and Wallet Hub will seamlessly integrate with the EUDI Wallet, enabling you to leverage its services for secure and reliable identification and authentication use cases. ## How to prepare To prepare for the arrival of the EUDI Wallet, you can already start integrating with our sandbox environments in the eID and Wallet Hub. Using a sandbox environment in Signicat Dashboard, you can familiarise yourself with the world of digital identification by using alternative electronic identities. This helps you to prepare for supporting the EUDI Wallet, once it becomes officially available. :::info Get started with the EUDI Wallet To get started with the EUDI Wallet, contact us by using the form below: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: ## Supported wallets Explore introductory guides for the identity wallets supported through the eID and Wallet Hub: --- ## Yivi Yivi is an app for digital identity that allows users in the Netherlands to store digitally signed personal properties (or attributes) from different trust issuers. Their data is stored in the Yivi app (or "wallet") from where users can then choose what attributes to disclose to others, for example when authenticating online. Yivi gives users the power to chose which attributes to reveal. With the Yivi mobile app, users can verify themselves accordingly, depending on the service they are using. When buying a movie on a streaming service, for example, an end-user can reveal they are older than 16, without having to prove who they are. Yivi is an digital identity wallet preparing to align with the European Digital Identity (EUDI) Wallet standards to support attribute-based credentials. ## Yivi roles In the Yivi framework, the following roles exist: 1. **Users:** The end-users who have Yivi on their phone, containing cards with personal data. Users identify themselves with Yivi by sharing relevant data from their digital cards. 2. **Verifiers:** The organisations that want to know something about users and request that information through Yivi. Users disclose their data to verifiers. 3. **Issuers:** The organisations that issue personal or other data types to users, in the form of cards in their Yivi app. Users can then identify themselves to verifiers with the data on those cards. The **verifier** can verify that certain attributes were given to the **user** in the past by validating the **issuer**'s digital signature. They can then confirm that the attributes have not been modified since they were previously authenticated. ## Key features - Free and open source. - A safe and secure method of authentication for the end-users. - End-users choose when they share data from the data cards, and who they share it with. - No fixed set of attributes provided. The end-user fills their Yivi wallet with verified attributes from various sources to then be enclosed to a verifier when the user gives consent. - End-users can digitally sign documents by disclosing only selected relevant attributes about themselves. ## Yivi app The Yivi app is a free mobile application that allows users to control the data they want to disclose when they log in, share data and prove who they are online. The app is created by the Privacy by Design Foundation. You can download the app for free from the [Download Yivi page](https://www.yivi.app/en/download). ## External resources * For more information about Yivi, visit [https://www.yivi.app/](https://www.yivi.app/en/). * Yivi for developers is available at [https://www.yivi.app/en/for-developers](https://www.yivi.app/en/for-developers). ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Signicat eID and Wallet Hub The eID and Wallet Hub allows you to verify the identity of users who log in to your online service(s). You do this by connecting your application to identity wallets and electronic identities (eIDs), such as Norwegian BankID, FTN and MitID. The eID and Wallet Hub gives you access to a hub of European eIDs and wallets through a single point of integration with the following authentication protocols: - OpenID Connect (OIDC) - Security Assertion Markup Language (SAML) 2.0 - Signicat Authentication REST API Discover our developer guides and get started below. ## Guides * [**Quick start guide**](/docs/eid-hub/quick-start/): Get started with the eID and Wallet Hub in minutes * [**Demo**](/docs/eid-hub/demo/): Try out an eID in a few clicks * [**Concepts**](/docs/eid-hub/concepts/): Learn about the core concepts of the eID and Wallet Hub ## eIDs The eID and Wallet Hub offers a wide selection of eIDs to authenticate your end-users in most European countries. Learn more about eIDs, follow our integration guides and discover use cases: export const IDMethodsDisplay = ['nbid', 'sbid', 'finnisheid', 'digid', 'email-otp', 'itsme', 'mitid', 'mobileid', 'sms-otp'] eidMethods.find(method => method.id === idMethod))} withoutSelect columns={3} /> [**View all eIDs**](/docs/eid-hub/e-ids) Explore our guides to set up and test an eID. * [**Add eIDs**](/docs/eid-hub/e-ids/add-eids): Activate an eID in the Signicat Dashboard * [**Test eIDs**](/docs/eid-hub/e-ids/test-eids): Start testing and understand the user journey * [**Simulator**](/docs/eid-hub/e-ids/simulator): Customise your testing environment with the simulator ## Identity wallets The eID and Wallet Hub allows you to authenticate users and businesses with the EU Digital Identity Wallet. Learn more about identity wallets, follow our integration guides and discover use cases: Explore how authentication with identity wallets works. * [**Identity wallets**](/docs/eid-hub/identity-wallets): Get started with the EU Digital Identity Wallet ## Authentication protocols To authenticate your end-users using eIDs or wallets, you need to set up a connection between your application and the eID and Wallet Hub by using an authentication protocol. Below, you find documentation specific to each protocol: * [**OIDC**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains. * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users. ### Advanced customisation The eID and Wallet Hub is a flexible and dynamic product that you can customise to fit your needs. Learn more in the Advanced guides below: * [**Events and webhooks**](/docs/dashboard/settings/events): Subscribe to events from Signicat services * [**Account theming**](/docs/dashboard/branding/theming): Continue to configure the look and feel of your account ## Connectors Take eIDs from the Signicat eID and Wallet Hub with you across platforms and third-party providers. Learn more in our Connectors guides: * [**Auth0**](/docs/eid-hub/connectors/auth0-integration): Learn how to integrate Signicat with your Auth0 tenant ## Migration guides If you are an existing customer migrating to our new platform, take a look at our migration guides: * [**Migrating from Enterprise Authentication**](/docs/eid-hub/migration-guides/enterprise/): Migrate to our new Digital Trust Platform * [**Migrating from Signicat Identity Broker**](/docs/eid-hub/migration-guides/signicat-identity-broker/): Migrate to our new Digital Trust Platform --- ## Changes for Finnish Trust Network (FTN) This page describes the changes specific to Finnish Trust Network (FTN) that are required when migrating an existing OIDC integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP). ## Overview - FTN authentication works the same after migration. - The end-user authentication flow does not require any changes specific to FTN. - The main migration changes affect: - OIDC configuration, including your endpoints and client credentials. - Returned OIDC claims. - Mandatory Message-Level Encryption (MLE). - Authentication request signing. - Identity method selection (if used). :::warning FTN security requirements For FTN, you must sign or send your authentication requests using [Pushed Authorization Requests (PAR)](/docs/eid-hub/oidc/advanced-security/pushed-authorization-requests-par/). Also, OIDC responses must use full [Message-Level Encryption (MLE)](/docs/eid-hub/oidc/advanced-security/receive-encrypted-signed-responses/), which requires an encryption key that needs to be configured on the OIDC client in our new platform before testing. Without this configuration, authentication will fail and no result will be returned. To learn more, see the [Message level encryption](#message-level-encryption) section. ::: ## Claims For an overview of the key claim changes, see the table below: :::CustomTable{tableName="Overview of FTN claims" columnWidths="25% 25% 50%"} | **Enterprise claim** | **New platform claim** | **Description** | | :-- | :-- | :-- | | `signicat.national_id` | `nin` | A different claim name, but the same value (Finnish national identity number) is returned. | | Not returned | `nin_type` | Indicates the type of national identity number.**Example**: `PERSON`. | | `locale` | `nin_issuing_country` | Indicates the issuing country of the national identity number.**Note**: For FTN, this is `FI`. | | `ftn.idpId` | `ftn_idp` | A different claim name, but the same value is returned. **Note**: For an overview of the providers, see the [Provider scoping](/identity-methods/ftn/attributes-reference/#provider-scoping) section in the FTN **Attributes reference**. **Example**: `fi-nordea`. | | `ftn.sub` | `ftn_sub` | A different claim name, but the same value is returned. | | `ftn.hetu` | `ftn_hetu` | A different claim name, but the same value is returned (Finnish national identity number). | | Not returned | `ftn_issuer` | Identifies the issuer used by the underlying FTN provider. | | `sub` | `sub` | The same claim name, but a different value is returned after migration (unless Enterprise subject lookup is used). | | Not returned | `idp_issuer` | Identifies the underlying FTN identity provider. | ::: :::note Note The standard claims `name`, `given_name`, `family_name`, `birthdate` and `gender` remain unchanged. For a complete list of Finnish Trust Network (FTN) claims, see the [Attributes reference](/identity-methods/ftn/attributes-reference/) page. ::: ## Scopes When migrating FTN, we recommend using the same set of scopes as in your current integration, while applying the mapping of the scope codes. For example, if you currently use `openid`, `profile` and `signicat.national_id`, we recommend that you replace `signicat.national_id` with `nin` thus resulting in `openid`, `profile` and `nin`. This ensures that you receive the equivalent user information. ```text title="Example: Scopes" openid profile nin ``` :::tip Our recommendation We recommend that you only use additional FTN scopes if your application already depends on them, such as the `ftn-extra` scope which returns `ftn_idp`, `ftn_sub`, `ftn_issuer` and `ftn_hetu`. You should only use the `idp-id` scope if your application requires the separate `idp_id` claim. ::: The exact claims returned depend on the requested scopes and your OIDC client configuration. You can find an example of how an OIDC authentication response and used scopes differ between Enterprise and our new platform below: ```text title="Example: Enterprise OIDC scopes" openid+ftn+profile+signicat.national_id ``` ```json title="Example: Enterprise response" { "ftn.sub": "", "sub": "", "birthdate": "2000-02-01", "gender": "male", "ftn.hetu": "", "name": "Onni Juhani Korhonen", "signicat.national_id": "", "locale": "FI", "given_name": "Onni Juhani", "ftn.idpId": "fi-nordea", "family_name": "Korhonen" } ``` ```text title="Example: New platform scopes" openid+ftn-extra+profile+nin ``` ```json title="Example: New platform response" { "name": "Onni Juhani Korhonen", "family_name": "Korhonen", "given_name": "Onni Juhani", "gender": "male", "birthdate": "2000-02-01", "nin": "", "nin_type": "PERSON", "nin_issuing_country": "FI", "ftn_idp": "fi-nordea", "ftn_sub": "", "ftn_issuer": "https://identify.nordea.com", "ftn_hetu": "", "idp_issuer": "https://identify.nordea.com", "sub": "" } ``` ## Required application changes Update your application to read the Finnish national identity number from the new platform claim `nin`, instead of the Enterprise `signicat.national_id` claim: ```text title="Enterprise claim" signicat.national_id ``` ```text title="New platform claim" nin ``` You also need to update your application to read FTN-specific claims using underscores (`_`) instead of full stops (`.`): ```text title="Example: Enterprise claims" ftn.sub ftn.hetu ftn.idpId ``` ```text title="Example: New platform claims" ftn_sub ftn_hetu ftn_idp ``` If your application uses the OIDC `sub` claim as an internal user identifier, then you must verify your identifier mapping before migration. :::note Note The `sub` claim is still returned by our new platform, but the value may differ from the Enterprise value. If you need to retrieve the identical `subID` value, then you can follow the [Migrating from Enterprise](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc/) documentation. ::: ## ACR values The `acr_values` parameter is optional. You should only use it if your application pre-selects FTN or a specific FTN provider. ### Pre-select FTN To pre-select FTN in our new platform, set `idp:ftn` in the `acr_values`. ```text title="Starting FTN authentication" acr_values=idp:ftn ``` This routes the end-user directly to the FTN provider selection page. ### Pre-select an FTN provider To pre-select a specific FTN provider, also specify `ftn_idp` in the `acr_values`. ```text title="Starting Nordea authentication" acr_values=idp:ftn ftn_idp:fi-nordea ``` For available FTN providers and additional request parameters, see the [FTN OIDC integration guide](/identity-methods/ftn/integration-guide/oidc-ftn/). ## Message-level encryption FTN requires message-level encryption (MLE). You must configure an encryption key on the OIDC client for our new platform before testing the FTN integration. Without this configuration, FTN authentication will fail and no authentication result will be returned. Learn more about [Encrypted/signed responses from Signicat](/docs/eid-hub/oidc/advanced-security/receive-encrypted-signed-responses/). :::info What does this mean? Our new platform encrypts the ID token and UserInfo response using a public encryption key configured on the OIDC client. Your application must use the corresponding private key to decrypt the responses. ::: ### 1. Configure the encryption key You can configure the encryption key in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. From the OIDC client management page, locate your OIDC client, then click the **Edit** button. :::tip Tip This is the OIDC client that you created when following the **Enterprise to new platform** migration **Quick start guide**, in the [Create a connection](/docs/eid-hub/migration-guides/enterprise/quick-start-guide/#3-create-a-connection) section. ::: 3. Click the **Advanced** tab, then click **Public keys**. 4. Choose either the **Import public key** or **+ Add public key** button, depending on what option you want to proceed with. Follow the corresponding steps under either [Option 1](#option-1-reuse-the-existing-enterprise-encryption-key) or [Option 2](#option-2-generate-a-new-encryption-key) below. #### Option 1: Reuse the existing Enterprise encryption key You can use this option if you want your application to continue using its existing private key. Only the public key is uploaded to our new platform. To do this: 1. Copy or export the public part of your Enterprise encryption key pair. 2. From the **Public keys** page in the Signicat Dashboard, click the **Import public key** button. 3. Enter a name, set the validation dates, then set **Encryption** for the **Usage** field. 4. Either paste the key in the **Data** field, or upload it using the **Upload file** button. 5. To finish, click the **Upload button** #### Option 2: Generate a new encryption key You can use this option if you want to rotate the encryption key during migration. To do this: 1. From the **Public keys** page in the Signicat Dashboard, click the **+ Add public key** button. 2. Enter a name, set the validation dates, then set **Encryption** for the **Usage** field. 3. To generate the key pair, click the **Create button**. 4. Copy the private key using the copy button, then securely store it. 5. Configure your application to use the new private key. :::info Want to learn more? For supported key formats and technical requirements, see the [Encrypted and signed responses from Signicat](/docs/eid-hub/oidc/advanced-security/receive-encrypted-signed-responses/) page. ::: ### 2. Enable encrypted responses After adding the encryption key, you need to enable encrypted responses in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. From the OIDC client management page, locate your OIDC client, then click the **Edit** button. :::tip Tip This is the OIDC client that you created when following the **Enterprise to new platform** migration **Quick start guide**, in the [Create a connection](/docs/eid-hub/migration-guides/enterprise/quick-start-guide/#3-create-a-connection) section. ::: 3. Click the **Advanced** tab, then click **Security**. 4. Under the **User Info response type** section, use the dropdown menu to select **SignedAndEncrypted**. 5. Tick the **Require encrypted ID tokens** box. 6. To save the client, click the **Update** button. Your application must then: 1. Decrypt the ID token or UserInfo response using its private key. 2. Read the signed JWT contained inside the encrypted response. 3. Validate the signed JWT as normal. :::note Note The encrypted response is a nested JWT. It must be decrypted before the claims can be read. ::: ## Authentication request signing FTN requires signed authentication requests. You must use one of the following: - A signed OIDC request object. - Pushed Authorization Requests (PAR). ### Option 1: Signed request objects If you use signed request objects, then you must configure the corresponding signing public key on the OIDC client for our new platform. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. From the OIDC client management page, locate your OIDC client, then click the **Edit** button. :::tip Tip This is the OIDC client that you created when following the **Enterprise to new platform** migration **Quick start guide**, in the [Create a connection](/docs/eid-hub/migration-guides/enterprise/quick-start-guide/#3-create-a-connection) section. ::: 3. Click the **Advanced** tab, then click **Public keys**. 4. If you have an existing key, you can configure this with the **Edit** button. If not, then you can upload or create a new one with the **Import public key** or **+ Add public key** buttons. 5. If applicable, complete the name and validation date fields. Then, ensure that you set **Signing** for the **Usage** field. 6. Finalise editing, uploading or generating the new keys. 7. Your application must then keep the matching private key, and use it to sign each request object. :::info Want to learn more? To learn how to implement, see the [Encryption/signing of the request object](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests/) page. ::: ### Option 2: Pushed Authorization Requests (PAR) To learn how to implement Pushed Authorization Requests (PAR), see the [Pushed Authorization Requests](/docs/eid-hub/oidc/advanced-security/pushed-authorization-requests-par/) page. ## Test before cutover Migrating FTN authentication to our new platform has a low impact on the end-user authentication experience. However, FTN requires additional security requirements, including mandatory message-level encryption (MLE) and signed authentication requests. Note that you need to configure and implement these additional security requirements in our new platform. Before production cutover, verify that your application can: - Complete an FTN OIDC authentication flow in our new platform. - Read the Finnish national identity number from `nin` instead of `signicat.national_id`. - Read FTN-specific claims using underscore-based names (for example, `ftn_sub` and `ftn_idp`). - Successfully decrypt encrypted OIDC responses using the configured private key. - Send signed authentication requests or use Pushed Authorization Requests (PAR), as required. - Handle any changes to the `sub` value if it is used as an internal identifier. - Pre-select FTN using `acr_values=idp:ftn`, if your application uses method pre-selection. - Pre-select the correct FTN provider, if your application uses provider pre-selection. --- ## Changes for eIDs Learn about changes specific to the eIDs that you are using, to help ensure a smooth transition between Signicat Enterprise and the new Signicat Digital Trust Platform (DTP). * [**Changes for Norwegian BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/nbid): Learn about migration changes specific to Norwegian BankID * [**Changes for Swedish BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/sbid): Learn about migration changes specific to Swedish BankID * [**Changes for MitID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/mitid): Learn about migration changes specific to MitID * [**Changes for Finnish Trust Network (FTN)**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/ftn): Learn about migration changes specific to Finnish Trust Network (FTN) --- ## Changes for MitID This page describes the changes specific to MitID that are required when migrating an existing OIDC integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP). ## Overview - MitID authentication works the same after migration. - The end-user authentication flow does not require any changes specific to MitID. - The main migration changes affect: - OIDC configuration, including your endpoints and client credentials. - Returned OIDC claims. - Requested scopes. - ACR values (if used). ## Claims For an overview of the key claim changes, see the table below: :::CustomTable{tableName="Overview of MitID claims" columnWidths="25% 25% 50%"} | **Enterprise claim** | **New platform claim** | **Description** | | :-- | :-- | :-- | | `signicat.national_id` or `mitid.cpr` | `nin` | A different claim name, but the same value (CPR number) is returned.**Note**: CPR matching must be enabled. | | Not returned | `nin_type` | Indicates the type of national identity number.**Example**: `PERSON`. | | Not returned | `nin_issuing_country` | Indicates the issuing country of the national identity number.**Note**: For MitID, this is `DK`. | | `mitid.has_cpr` | `mitid_has_cpr` | A different claim name, but the same value is returned. | | `mitid.transaction_id` | `mitid_transaction_id` | A different claim name, but the same value is returned. | | `mitid.reference_text_body` | `mitid_reference_text_body` | A different claim name, but the same value is returned. | | `mitid.cpr.source` | `mitid_cpr_source` | A different claim name, but the same value is returned. | | Not returned | `mitid_name_and_address_protection` | This is returned when the end-user has name and address protection. **Note**: This returns either `true` or `false`. | | `mitid.ial` or `mitid.ial_identity_assurance_level` | `mitid_ial` | A different claim name, but the same value is returned. | | `mitid.loa` | `mitid_loa` | A different claim name, but the same value is returned. | | `mitid.aal` | `mitid_aal` | A different claim name, but the same value is returned. | | `mitid.fal` | `mitid_fal` | A different claim name, but the same value is returned. | | `mitid.uuid` | `mitid_uuid` | A different claim name, but the same value is returned. | | `mitid.identity_name` | `name` | Now returned using the standard OIDC `profile` claim. | | `sub` | `sub` | The same claim name, but a different value is returned after migration (unless Enterprise subject lookup is used). | | Not returned | `idp_issuer` | Identifies the underlying MitID identity provider. | | `mitid.age` | Not returned | If your application depends on these claims, you must verify the required configuration of our new platform or update the application before production cutover. | | `mitid.psd2` | Not returned | If your application depends on these claims, you must verify the required configuration of our new platform, or update the application before production cutover. | ::: :::note Note The standard claims `name`, `given_name`, `family_name`, `birthdate` and `gender` remain unchanged. For a complete list of MitID claims, see the [Attributes reference](/identity-methods/mitid/attributes-reference/) page. ::: ## Scopes When migrating MitID, we recommend using the same set of scopes as in your current integration, while applying the mapping of the scope codes. For example, if you currently use `openid`, `profile` and `signicat.national_id`, we recommend that you replace `signicat.national_id` with `nin` thus resulting in `openid`, `profile` and `nin`. This ensures that you receive the equivalent user information. ```text title="Example: Scopes" openid profile nin ``` :::tip Our recommendation We recommend that you only use additional MitID scopes if your application already depends on them, such as `mitid-extra`. ::: The exact claims returned depend on the requested scopes, the OIDC client configuration, CPR matching, and any optional MitID functionality used by the integration. Some MitID claims are conditional and are therefore not returned in every authentication response. :::info What does this mean? For example, when name and address protection applies, `mitid_name_and_address_protection` may be returned and the standard name claims may be omitted. ::: You can find an example of how an OIDC authentication response and used scopes differ between Enterprise and our new platform below: ```text title="Example: Enterprise OIDC scopes" openid+mitid+profile+signicat.national_id+signicat.organization ``` ```json title="Example: Enterprise response" { "sub": "", "birthdate": "1902-12-18", "name": "Petter Johnson", "signicat.national_id": "", "given_name": "Petter", "family_name": "Johnson", "mitid.has_cpr": "true", "mitid.transaction_id": "41497a86-390d-4110-b4bd-ffca35aace8a", "mitid.reference_text_body": " ", "mitid.cpr.source": "user", "mitid.ial": "HIGH", "mitid.loa": "HIGH", "mitid.aal": "HIGH", "mitid.fal": "HIGH", "mitid.uuid": "b3c6cddf-0b8e-4760-a38b-45afccfca30a" } ``` ```text title="Example: New platform scopes" openid+mitid-extra+profile+nin ``` ```json title="Example: New platform response" { "name": "Petter Johnson", "family_name": "Johnson", "given_name": "Petter", "birthdate": "1902-12-18", "nin": "", "nin_type": "PERSON", "nin_issuing_country": "DK", "mitid_has_cpr": "true", "mitid_transaction_id": "41497a86-390d-4110-b4bd-ffca35aace8a", "mitid_reference_text_body": " ", "mitid_cpr_source": "user", "mitid_ial": "HIGH", "mitid_loa": "HIGH", "mitid_aal": "HIGH", "mitid_fal": "HIGH", "mitid_uuid": "b3c6cddf-0b8e-4760-a38b-45afccfca30a", "idp_issuer": "MitID", "sub": "" } ``` ## Required application changes Update your application to read the CPR number from the new platform claim `nin`, instead of the Enterprise `signicat.national_id` or `mitid.cpr` claim: ```text title="Enterprise claim" signicat.national_id ``` ```text title="Enterprise claim" mitid.cpr ``` ```text title="New platform claim" nin ``` Update your application to read claims specific to MitID using underscores (`_`) for our new platform, instead of full stops (`.`) for Enterprise: ```text title="Example: Enterprise claim with fullstop" mitid.transaction_id ``` ```text title="Example: New platform claim with underscore" mitid_transaction_id ``` To verify that CPR matching works as expected, make sure that `nin` is one of the requested scopes in the authorisation request: - A CPR number entered by the end-user. - A previously cached CPR number. If your application uses the OIDC `sub` claim as an internal user identifier, then you must verify your identifier mapping before migration. :::note Note The `sub` claim is still returned by our new platform, but the value may differ from the Enterprise value. If you need to retrieve the identical `subID` value, then you can follow the [Migrating from Enterprise](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc) documentation. ::: ## ACR values The `acr_values` parameter is optional. You should only use it if your application pre-selects MitID. ### Pre-select MitID To pre-select MitID in our new platform, set `idp:mitid` in the `acr_values`. ```text title="Starting MitID authentication" acr_values=idp:mitid ``` :::note Note When MitID is the only method specified, the user is routed directly to MitID without seeing the identity method selection screen. ::: ### Additional MitID request parameters For additional MitID request parameters, see the [MitID OIDC integration guide](/identity-methods/mitid/integration-guide/oidc-mitid/). This includes: - Native app switching. - Transaction reference text. - Other MitID-specific request options. ## Test before cutover Migrating MitID authentication to our new platform has a low overall impact. End-users authenticate in the same way, and the returned OIDC response is largely unchanged. Before production cutover, verify that your application can: - Complete a MitID OIDC authentication flow in our new platform. - Read the CPR number from `nin` instead of `signicat.national_id` or `mitid.cpr`. - Read MitID-specific claims using underscore-based names (for example, `mitid_transaction_id`). - Handle conditional claims, including users with name and address protection. - Handle any changes to the `sub` value if it is used as an internal identifier. - Pre-select MitID using `acr_values=idp:mitid`, if your application uses method pre-selection. - Verify any additional MitID functionality used by your integration. --- ## Changes for Norwegian BankID This page describes the changes specific to Norwegian BankID that are required when migrating an existing OIDC integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP). ## Overview - Norwegian BankID authentication works the same after migration. - Your end-users will experience the exact same authentication flow as before. - The end-user flow does not require any changes specific to Norwegian BankID. - The main migration changes affect: - OIDC configuration, including your endpoints and client credentials. - Returned OIDC claims, including the Norwegian national identity number. ## Claims For an overview of the key claim changes, see the table below: :::CustomTable{tableName="Overview of Norwegian BankID claims" columnWidths="25% 25% 50%"} | **Enterprise claim** | **New platform claim** | **Description** | | :-- | :-- | :-- | | `signicat.national_id` | `nin` | A different claim name, but the same value is returned. | | Not returned | `nin_type` | Indicates the type of national identity number. **Example**: `BIRTH`. | | `locale` | `nin_issuing_country` | Indicates the issuing country of the national identity number. **Note**: For Norwegian BankID, this is `NO`. | | `sub` | `sub` | The same claim name, but a different value is returned after migration (unless Enterprise subject lookup is used). | | Not returned | `idp_issuer` | Indicates the underlying provider for Norwegian BankID. | ::: :::note Note The standard claims `name`, `given_name`, `family_name`, `birthdate` and `gender` remain unchanged. For a complete list of Norwegian BankID claims, see the [Attributes reference](/identity-methods/nbid/attributes-reference/) page. ::: ## Scopes When migrating Norwegian BankID, we recommend using the same set of scopes as in your current integration, while applying the mapping of the scope codes. For example, if you currently use `openid`, `profile` and `signicat.national_id`, we recommend that you replace `signicat.national_id` with `nin` thus resulting in `openid`, `profile` and `nin`. This ensures that you receive the equivalent user information. ```text title="Example: Scopes" openid profile nin ``` :::tip Our recommendation We recommend that you only use additional Norwegian BankID scopes if your application already depends on them. ::: The exact claims returned depend on the requested scopes and your OIDC client configuration. You can find an example of how an OIDC authentication response and the scopes used differ between Enterprise and our new platform below: ```text title="Example: Enterprise OIDC scopes" openid+profile+signicat.national_id ``` ```json title="Example: Enterprise response" { "sub": "", "birthdate": "2002-12-18", "name": "Petter Jensen Emdal", "signicat.national_id": "", "given_name": "Petter Jensen", "locale": "NO", "family_name": "Emdal" } ``` ```text title="Example: New platform scopes" openid+profile+nin ``` ```json title="Example: New platform response" { "name": "Petter Jensen Emdal", "family_name": "Emdal", "given_name": "Petter Jensen", "birthdate": "2002-12-18", "nin": "", "nin_type": "BIRTH", "nin_issuing_country": "NO", "sub": "", "idp_issuer": "https://auth.bankid.no/auth/realms/prod" } ``` ## Required application changes Update your application to read the Norwegian national identity number from the new platform claim `nin`, instead of the Enterprise `signicat.national_id` claim: ```text title="Enterprise claim" signicat.national_id ``` ```text title="New platform claim" nin ``` If your application uses the OIDC `sub` claim as an internal user identifier, then you must verify your identifier mapping before migration. :::note Note The `sub` claim is still returned by our new platform, but the value may differ from the Enterprise value. If you need to retrieve the identical `subID` value, then you can follow the [Migrating from Enterprise](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc/) documentation. ::: ## ACR Values The way in which you define the different flows of Norwegian BankID has also changed with this migration. - Previously, you defined the flow using separate method names for level of assurance (LoA) _high_ or _substantial_ transactions. - Now, you define the flow using ACR values. :::note Note The default Norwegian BankID product uses a LoA _high_ as its flow. If you have not specifically purchased _substantial_ as an option, then you may not be able to access the _substantial_ flow. ::: | **Name** | **Value** | **Description** | | :-- | :-- | :-- | | `nbid_idp` | `BID` or `BIS` | Specifies the required Norwegian BankID type, where `BID` is **BankID High** with _high_ LoA, and `BIS` is **BankID Biometric** with _substantial_ LoA. **Note**: If no value is provided, the end-user can select `BID` by default. This parameter works with `login_hint`. | ```text title="Setting Norwegian BankID flow in ACR values" acr_values=idp:nbid nbid_idp:BIS ``` ## Test before cutover Migrating Norwegian BankID authentication to our new platform has a low overall impact. End-users authenticate in the same way, and the returned OIDC response is largely unchanged. Before production cutover, verify that your application can: - Complete a Norwegian BankID OIDC authentication flow in our new platform. - Read the national identity number from `nin` instead of `signicat.national_id`. - Read `name`, `given_name`, `family_name`, and `birthdate`. - Handle any changes to the `sub` value if it is used as an internal identifier. - Start the required Norwegian BankID flow using the appropriate `acr_values` (for example, `acr_values=idp:nbid nbid_idp:BIS`), if your application specifies a particular BankID type. --- ## Changes for Swedish BankID This page describes the changes specific to Swedish BankID that are required when migrating an existing OIDC integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP). ## Overview - Swedish BankID authentication works the same after migration. - The end-user authentication flow does not require any changes specific to Swedish BankID. - The main migration changes affect: - OIDC configuration, including your endpoints and client credentials. - Returned OIDC claims, including the Swedish national identity number. - Identity method selection (if used). ## Claims For an overview of the key claim changes, see the table below: :::CustomTable{tableName="Overview of Swedish BankID claims" columnWidths="25% 25% 50%"} | **Enterprise claim** | **New platform claim** | **Description** | | :-- | :-- | :-- | | `signicat.national_id` | `nin` | A different claim name, but the same value is returned. | | Not returned | `nin_type` | Indicates the type of national identity number. **Example**: `PERSON`. | | `locale` | `nin_issuing_country` | Indicates the issuing country of the national identity number. **Note**: For Swedish BankID, this is `SE`. | | `sub` | `sub` | The same claim name, but a different value is returned after migration (unless Enterprise subject lookup is used). | | Not returned | `idp_issuer` | Indicates the underlying provider for Swedish BankID. | ::: :::note Note The standard claims `name`, `given_name`, `family_name`, `birthdate` and `gender` remain unchanged. For a complete list of Swedish BankID claims, see the [Attributes reference](/identity-methods/sbid/attributes-reference/) page. ::: ## Scopes When migrating Swedish BankID, we recommend using the same set of scopes as in your current integration, while applying the mapping of the scope codes. For example, if you currently use `openid`, `profile` and `signicat.national_id`, we recommend that you replace `signicat.national_id` with `nin` thus resulting in `openid`, `profile` and `nin`. This ensures that you receive the equivalent user information. ```text title="Example: Scopes" openid profile nin ``` :::tip Our recommendation We recommend that you only use additional Swedish BankID scopes if your application already depends on them. ::: The exact claims returned depend on the requested scopes and your OIDC client configuration. You can find an example of how an OIDC authentication response and the scopes used differ between Enterprise and our new platform below: ```text title="Example: Enterprise OIDC scopes" openid+profile+signicat.national_id ``` ```json title="Example: Enterprise response" { "sub": "", "birthdate": "1976-11-19", "name": "Marcus Johnsson", "signicat.national_id": "", "given_name": "Marcus", "locale": "SV", "family_name": "Johnsson" } ``` ```text title="Example: New platform scopes" openid+profile+nin ``` ```json title="Example: New platform response" { "name": "Marcus Johnsson", "family_name": "Johnsson", "given_name": "Marcus", "birthdate": "1976-11-19", "nin": "", "nin_type": "PERSON", "nin_issuing_country": "SE", "sub": "", "idp_issuer": "sbid" } ``` ## Required application changes Update your application to read the Swedish national identity number from the new platform claim `nin`, instead of the Enterprise `signicat.national_id` claim: ```text title="Enterprise claim" signicat.national_id ``` ```text title="New platform claim" nin ``` If your application uses the OIDC `sub` claim as an internal user identifier, then you must verify your identifier mapping before migration. :::note Note The `sub` claim is still returned by our new platform, but the value may differ from the Enterprise value. If you need to retrieve the identical `subID` value, then you can follow the [Migrating from Enterprise](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc) documentation. ::: ## ACR values The `acr_values` parameter is optional. You should only use it if your application pre-selects Swedish BankID or controls a specific Swedish BankID flow. ### Pre-select Swedish BankID and control authentication flow To pre-select Swedish BankID in our new platform, set `idp:sbid` in the `acr_values`. ```text title="Starting default Swedish BankID flow" acr_values=idp:sbid ``` To specify which authentication flow to use, you must also include it in the `acr_values` parameter. The examples below show how to predefine the flow to either display a QR code or launch the app on the same device. ```text title="Starting Swedish BankID QR code flow" acr_values=idp:sbid sbid_initial_flow:REMOTE_FLOW ``` ```text title="Starting Swedish BankID app launch flow" acr_values=idp:sbid sbid_initial_flow:APP_LAUNCH ``` :::note Note If you do not specify `sbid_initial_flow` in the `acr_values`, then the default behaviour is used and the appropriate flow is selected automatically based on the end-user's device. ::: ### Advanced Swedish BankID flows For advanced flow options, see the [Swedish BankID OIDC integration guide](/identity-methods/sbid/integration-guide/oidc-sbid/). This includes: - Phone flow. - MRTD. - Intention text. - App redirects. - iOS redirect behaviour. ## Test before cutover Migrating Swedish BankID authentication to our new platform has a low overall impact. End-users authenticate in the same way, and the returned OIDC response is largely similar. Before production cutover, verify that your application can: - Complete a Swedish BankID OIDC authentication flow in our new platform. - Read the national identity number from `nin` instead of `signicat.national_id`. - Read `name`, `given_name`, `family_name`, and `birthdate`. - Handle any changes to the `sub` value if it is used as an internal identifier. - Pre-select Swedish BankID using `acr_values=idp:sbid`, if your application uses method pre-selection. --- ## Enterprise to new platform In the guides below, you can learn how to migrate your integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP). :::note Who are these guides for? These guides are for existing Signicat Enterprise customers who have been invited to migrate to our new Digital Trust Platform. ::: ## Before you start Before you start, you will receive the following from Signicat so that you can begin your self-service migration: - An invitation to your organisation on our new platform. - Access to a sandbox account for testing. :::tip What does sandbox mean? On our new platform, **sandbox** refers to your pre-production environment. ::: :::details What is self-service migration? With self-service migration, you can configure domains, create connections and add eID methods yourself for both sandbox and production accounts. In production, certain eID methods may require activation or configuration by Signicat before they can be used. ::: :::details What does self-service migration look like? For an overview of what the migration process looks like, see the steps below. Most migrations follow these steps: 1. Open your sandbox account. 2. Set up your domain. 3. Create a connection using OIDC, Authentication REST API or SAML 2.0. 4. Add the eID methods you need. 5. Update your application configuration. 6. Test the integration in sandbox. 7. Create or request your production account. 8. Notify your Migration Manager when the production account is ready. 9. Complete production setup. 10. Plan and complete production cutover. ::: ### 1. Configure your new environment using Signicat Dashboard Learn how to set up your new environment using the Signicat Dashboard with our quick start guide. * [**Quick start guide**](/docs/eid-hub/migration-guides/enterprise/quick-start-guide): Set up your new environment in the Signicat Dashboard ### 2. Implement changes specific to eID Learn about changes specific to the eIDs that you are using, to help ensure a smooth transition between the old and new platform. * [**Changes for Norwegian BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/nbid): Learn about migration changes specific to Norwegian BankID * [**Changes for Swedish BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/sbid): Learn about migration changes specific to Swedish BankID * [**Changes for MitID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/mitid): Learn about migration changes specific to MitID * [**Changes for Finnish Trust Network (FTN)**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/ftn): Learn about migration changes specific to Finnish Trust Network (FTN) ## Additional resources To learn about how to do this based on the specific protocol, see the guides below. * [**Changes for OIDC**](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc): Learn about migration changes specific to OIDC --- ## Changes for OIDC This page applies to customers interested in migrating from Enterprise to the new Signicat Digital Trust Platform (DTP), our new platform for digital identity. Below, you can find more context to help you understand what has changed, next to suggestions for migrating in a seamless way. For our new platform, we have built a new **OpenID Connect** server to provide consistent naming for scopes and claims, and improved configuration options. The new server is certified by the OpenID Connect Foundation and offers more flexibility while adhering better to standards. You can read more about this in the [OIDC Server documentation](/docs/eid-hub/oidc/#signicat-oidc-server). ## Key differences The platforms differ on the following features: - [**Endpoints**](#endpoints): Changes to domains and paths while keeping the same endpoints. - [**Token structure**](#token-structure): Same basic structure with differences in claims name and values. - [**Scopes and claims**](#scopes-and-claims): Changes to National ID and IdP-specific scopes and claims. - [**Key rotation**](#key-rotation): Keys are rotated more often. - [**Request parameters**](#request-parameters): Changes to the format and values of certain OIDC request parameters. - [**Subject IDs**](#subject-ids): Access Enterprise subject IDs in our new platform after migration. - [**Finnish Trust Network (FTN) specifics**](#finnish-trust-network-ftn-specifics): Different implementation of MLE. - [**SSO and SLO**](#sso-and-slo): Default SSO for new clients and improved SLO support. :::note Note While this page covers the changes that affect your OIDC integration(s) towards Signicat, note that our new platform has also changed in terms of organisation management, eIDs and platform design. Read more about high-level concepts in the [General information](/docs/) section or find answers to common questions about OIDC in the [OIDC FAQs](/docs/eid-hub/oidc/faqs.mdx). ::: ## Endpoints All endpoints have changed and new endpoints have been added. You can find an overview of the endpoints in the OpenID well-known configuration endpoint. :::CustomTable{columnWidths="50% 50%"} | Enterprise endpoint | New platform endpoint | | :-- | :-- | | `https://{ENV}.signicat.com/oidc/.well-known/openid-configuration` | `https://{YOUR_SIGNICAT_DOMAIN}/auth/open/.well-known/openid-configuration` | ::: An example OpenID well-known configuration endpoint for our new platform is [https://demo.app.signicat.com/auth/open/.well-known/openid-configuration](https://demo.app.signicat.com/auth/open/.well-known/openid-configuration). ## Token structure The basic structure of tokens is defined by standards, and therefore token structure has not changed. However, we added, removed and updated some claims for the access and ID tokens, as displayed in the tables below: ### Access token :::CustomTable{columnWidths="20% 20% 60%"} | Enterprise claim | New platform claim | Comment | | :-- | :-- | :-- | | `iss` | `iss` | Same name, but new values. New value because domain and path structure is different in our new platform. | | `scp` | `scope` | New name, but same value. | | `cid` | `client_id` | New name, but same value. | | `sub` | `sub` | Same name, but new values. Learn more in the [Subject IDs](#subject-ids) section. | | `snm` | - | Removed field. The concept of “service” does not apply in our new platform. You can deduce the account by looking at `client_id` and `iss`. | ::: ### ID token :::CustomTable{columnWidths="20% 20% 60%"} | Enterprise claim | New platform claim | Comment | | :-- | :-- | :-- | | `iss` | `iss` | Same name, but new values. New value because domain and path structure is different in our new platform. | | `amr` | `amr` | Same name, but new values. Our new platform has more accurate use of this field. It signifies the type of authentication for the sub-type, used for a given IdP. For example, 2FA, fingerprint, id-card. | | `acr` | `idp` | Same name, but new values. The usage of this field has been improved. The new claim `idp_id` is now used to signify which IdP the end-user used to authenticate. | | `sub` | `sub` | Same name, but new values. Learn more in the [Subject IDs](#subject-ids) section. | | - | `transaction_id` | New field. An internal transaction ID for our new platform, useful when contacting Signicat support. | | - | `sandbox` | New field. Boolean field to signify if the client belongs to a sandbox or production account. | ::: ## Scopes and claims Standard scopes and claims have not changed, but there are some specific changes covered below. ### Claim for National ID It is important to note that the old scope/claim `signicat.national_id` has been changed to `nin`. We updated this to avoid issues with coding libraries and to align with industry, and Signicat, standards. We offer support for mitigation by introducing a “Custom claim alias”. To use this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select your OIDC client. If you haven't configured a client, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the menu for the OIDC client, select **Advanced > Custom claims**, then **Add custom claim**. 4. Enter `nin` in the **Claim** box and enter `signicat.national_id` in the **Alias** box. 5. Now, select **Create**. With a “Custom claim alias”, the OIDC client will always return a `signicat.national_id` claim whenever it returns the `nin` claim. Both claims will have the same exact value. ### IdP-specific scopes and claims Scopes and claims specific to an identity provider may be different in our new platform. Learn more about IdP-specific scopes and claims in the [eIDs](/docs/eid-hub/e-ids/) documentation. ## Key rotation The signing and encryption keys that belong to the new Signicat OIDC server are rotated more frequently - on a weekly basis. We changed this to improve platform security. Learn more in our [Key rotation](/docs/eid-hub/oidc/oidc-implementation.mdx#key-rotation) page. ## Request parameters We changed the format of some OIDC request parameters. The details are below: ### ACR values The format of `acr_value` has changed to make the parameter more flexible, consistent and easier to use. Also, many new configuration options to control ACR values in our new platform are now available. :::warning Important Note that the way you use ACR values to specify IdPs (eIDs) has changed. If you use the old format, the `acr_value` will be ignored (as an unknown value) and the end-user will be presented with an IdP selection screen with all the IdPs available for that account. ::: Refer to [`acr_values` section](/docs/eid-hub/oidc/oidc-implementation.mdx#acr_values) for more details. ### Login hint The format for the `login_hint` parameter has changed. The available values may also have changed according to the IdP-specific definition. Learn more in the [login_hint](/docs/eid-hub/oidc/oidc-implementation.mdx#login_hint) documentation. ### Theming (Signicat profile) Theming has changed fundamentally in our new platform. The old Enterprise URL parameter `signicat_profile` is now ignored. Learn more in the [Theming](/docs/dashboard/branding/theming.mdx#openid-connect) documentation. ### Enterprise portals The Enterprise concept of portals for authentication to customise IdP selection screens has been deprecated in our new platform. You can mitigate this by specifying a list of IdPs in the ACR values or setting up an account with only certain IdPs enabled. Theming can also help to replicate some of the old functionality. ## Subject IDs Our new platform introduces a new format for Subject IDs. This might affect your migration, if you are using the Enterprise Subject IDs as a primary index key or other type of unique identifier for your internal user systems. The fact that our new platform has new subject IDs for the same physical persons can be a potential blocker for your migration journey. To mitigate this, we released a feature called “Enterprise Subject Lookups” that allows you to gain access to Enterprise subject IDs from our new platform after migration. Note that this is a temporary migration feature that will be deprecated once all customers have moved away from using old enterprise subject IDs and adopted the new platform format. If you plan to use the “Enterprise Subject Lookups” feature, we strongly recommend that you start mapping the (old) Enterprise subject IDs to the new platform subject IDs and prefer the latter when they are available to you. Following these steps early on will save you time when the old enterprise subject IDs will get deprecated. :::warning How to activate “Enterprise Subject Lookups” To enable the “Enterprise Subject Lookups” feature, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. “Enterprise Subject Lookups” will be enabled only if necessary in your migration to our new platform. ::: ## Finnish Trust Network (FTN) specifics The implementation of Message-Level Encryption (MLE) in our new platform has been improved. It is now more flexible and can be managed completely with self-service. Note that there are some differences in the implementation as explained in the [FTN specifics for OIDC section](/docs/eid-hub/oidc/oidc-implementation.mdx#finnish-trust-network-ftn-specifics) and in the [FTN documentation](/identity-methods/ftn/). ## SSO and SLO When you create a new OIDC client in our new platform, it will have Single sign-on (SSO) by default. Learn more in the [SSO](/docs/eid-hub/oidc/oidc-implementation.mdx#single-sign-on-sso) documentation. To reproduce the old Enterprise way without SSO, you can specify the URL parameter `prompt=login` in each authorisation request in our new platform. This prompts the end-user to authenticate each time. Our new platform also has better support for Single log-out (SLO). Learn more in the [SLO](/docs/eid-hub/oidc/oidc-implementation.mdx#single-log-out-slo) documentation. ## Next steps * [**Quick start guide**](/docs/eid-hub/quick-start/): Get started with the eID and Wallet Hub in minutes * [**OpenID Connect**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol --- ## Quick start for migrating from Enterprise to our new platform # Quick start guide Learn how to migrate your integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP), using the Signicat Dashboard. In this guide, you will learn how to: - Set up your new environment in the Signicat Dashboard. - Test your integration in sandbox - Prepare for production cutover. :::note Documentation scope The scope of this page covers the migration journey and how to get set up in the Signicat Dashboard. For integration changes specific to a particular protocol, see the relevant migration guides linked at the bottom of this page. ::: ## 1. Open your sandbox account You need to accept your invitation to the Signicat Dashboard and open your sandbox account. To do this: 1. Locate and open the Signicat Dashboard invitation email that we sent you. 2. Click the link in the email to accept the invitation. 3. In the [Signicat Dashboard](https://dashboard.signicat.com/), ensure that the sandbox account created for your migration is selected in the top navigation bar. If not, expand the dropdown menu, then select the sandbox account. :::note Note The sandbox account is what you will use to configure and test your new integration before making any production changes. ::: ## 2. Set up your domain You need to set up a domain for your account. This can be either a **standard domain** or a **custom domain**, as summarised in the table below. :::details What is a domain used for? A domain is a pointer to the Signicat operational environment that determines the URL at which Signicat products and metadata are available. Standard and custom domains offer the same technical capabilities; the choice between them is only a matter of preference. To learn more, see our [Domains](/docs/dashboard/organisation-management/domains/) documentation. ::: :::CustomTable{columnWidths="20% 40% 40%"} | **Domain type** | **Description** | **Example** | | :-- | :-- | :-- | | Standard domain| A Signicat-managed domain. This is normally the simplest option. |`your-company.sandbox.signicat.com` | | Custom domain | A domain owned by your organisation. DNS validation is required, and you can optionally provide your own certificate. | `login-sandbox.example.com` | ::: :::note Choose your domain type - To set up a standard domain, see the steps in the [Standard domain](#standard-domain) section below. - To set up a custom domain, see our [Custom domain](/docs/dashboard/organisation-management/domains/custom/) documentation (outside of this guide). ::: ### Standard domain You can set up a standard domain for your account in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains). 2. Click the **+ Add domain** button. 3. In the **Choose your domain type** dialogue box, click the **Standard domain** button. This takes you to the **Add standard domain** page. 4. In the **Domain name** field, enter your desired domain name, then click the **Add domain** button. 5. Optionally, you can set this as your default domain by clicking the **Set as default** button. 6. From the domain overview, ensure that your domain is marked with DNS status **Ready**. :::warning Important Remember to update your application's code and configuration to point to the standard domain address that you have created. ::: ## 3. Create a connection You need to create a connection using an authentication protocol. This can be either **OIDC**, **Authentication REST API** or **SAML 2.0**, as summarised in the table below. :::details What is an authentication protocol used for? An authentication protocol is used to set up a connection between your application and the eID and Wallet Hub, allowing you to authenticate your end-users using eIDs or wallets. When integrating with our new platform, we recommend using OIDC (OpenID Connect) or our REST-based Authentication API. If you currently use SAML, we recommend migrating to one of these authentication protocols moving forward. ::: :::CustomTable{columnWidths="30% 70%"} | **Authentication protocol** | **Description** | | :-- | :-- | | [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) | You can use this for browser-based authentication and standard OIDC integrations. | | [Authentication REST API](/docs/eid-hub/authentication-api/) | You can use this for API-driven authentication flows. | | [SAML 2.0](/docs/eid-hub/saml-2-0/) | You can use this for existing SAML integrations that are not moving to OIDC or Authentication REST API. | ::: :::note Choose your authentication protocol - To set up a connection using the OIDC authentication protocol, see the steps in the [OpenID Connect (OIDC)](#openid-connect-oidc) section below. - To set up a connection using the Authentication REST API authentication protocol, see our [Authentication REST API](/docs/eid-hub/authentication-api/) documentation (outside of this guide) - To set up a connection using the SAML 2.0 authentication protocol, see our [SAML 2.0](/docs/eid-hub/saml-2-0/) documentation (outside of this guide) ::: ### OpenID Connect (OIDC) You can set up a connection using the OIDC authentication protocol in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub**, then select [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) from the left-side menu. 2. Click the **+ Create client** button. 3. Complete the fields as shown in the table below: | **Field** | **Description** | | :-- | :-- | | Primary grant type | Select **Authorization code flow**, unless your integration requires another type of flow. | | Create client from template | You do not need to update this field. **No template** can remain selected. | | Client name | Enter a name for your client. This is shown to end-users on consent screens, and may appear in other places as well. | | Redirect URI | Add the redirect URI for your application. This is where your end-user will be redirected after authentication, and so it must exactly match the URI used by your application. **Note**: This must be HTTPS and an absolute URI. You can add more URIs once the client is created. | | Scope | Select the required scopes that you want to add from the dropdown menu. The `openid` scope is mandatory. **Example**: For example, you could add `nin` and `profile`. | :::tip Tip The scope `nin` is equivalent to the scope `signicat.national_id` on our enterprise platform. ::: 4. Click the **Create** button. 5. Click the **Add secret** to create one. This takes you to the **Secrets** tab on the client details page. 6. Select **+ Add secret** to create a secret. 7. Enter a name for the client secret, then select **Generate secret**. 8. Copy and store both the client ID and the client secret securely. This is the only time that you can view the client secret in clear text. :::warning Important You should never include a client secret in frontend code or an authorisation request. ::: :::info Want to learn more? To learn how to make additional client configurations, see our [OpenID Connect](/docs/eid-hub/oidc/) documentation. ::: ## 4. Add eID methods You need to add eID methods for your integration. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub**, then select [**eIDs**](https://dashboard.signicat.com/bca/authn) from the left-side menu. 2. Click the **+ Add new** button. 3. From the list of eIDs, click an eID that you would like to add, then click the **Add** button. 4. From the eID overview, ensure that the eID is marked with status **Active**. 5. Repeat steps 1-4 until you have added all the eIDs that you want for your integration. 6. From the eID overview, you can optionally click the **Test eIDs** button to test an eID before connecting your application. :::note Production configuration For production, some eIDs may require additional configuration by Signicat. This is explained in the [Create and configure production](#7-create-and-configure-production) section in this guide. ::: ## 5. Update your application Update your application to use our new platform. Typical changes include: - Domain - Endpoints - Client credentials - Scopes - Claims - eID-selection parameters :::note Note The updates highlighted below show the key changes that you need to make if you are using the OIDC authentication protocol. The exact changes depend on your account configuration. For method-specific and protocol-specific changes, see the [Related documentation](#related-documentation) section at the bottom of this page. ::: ### OpenID Connect (OIDC) If you are using the OIDC authentication protocol, then you need to make the following key changes: :::CustomTable{tableName="Application updates" columnWidths="20% 50% 30%"} | **Aspect** | **What to do** | **Example** | | :-- | :-- | :-- | | Domain | Use your domain for our new platform that you configured in **Step 2**. **Note**: See section [2. Set up your domain](#2-set-up-your-domain). | `https://your-company.sandbox.signicat.com` | | Endpoints | Use the endpoints for our new platform. **Note**: See section [Endpoints](#endpoints). | `/auth/open/connect/authorize` | | Client credentials | Use your client credentials for our new platform that you configured in **Step 3**. **Note**: See section [3. Create a connection](#3-create-a-connection). | `sandbox-round-apple-123` | | Scopes | Use the desired scopes for our new platform, as described in the method-specific migration documentation. Scopes can be subject to change for each eID. **Note**: See section [Related documentation](#next-steps). | `profile`, `nin` | | Claims | Use the desired claims for our new platform, as described in the method-specific migration documentation. **Note**: See section [Next steps](#next-steps). Claims can be subject to change for each eID. | `name`, `given_name`, `family_name`, `birthdate`, `nin` | | eID-selection parameters | Use the ACR values for our new platform as described in the method-specific migration documentation. | You now use the ACR values to determine the flow for the eID, such as the level of assurance for Norwegian BankID. | :::note Clients using PKCE If your client uses PKCE, you must also include the following: - `code_challenge` - `code_challenge_method=S256` ::: #### Endpoints You can find an overview of the main OIDC endpoint changes between Enterprise and our new platform below: :::tip Tip Where possible, configure your OIDC library using the discovery URL for our new platform, instead of hardcoding the individual endpoints. ::: ```text title="Discovery endpoint for Enterprise" https://preprod.signicat.com/oidc/.well-known/openid-configuration ``` ```text title="Authorization endpoint for Enterprise" https://preprod.signicat.com/oidc/authorize ``` ```text title="Token endpoint for Enterprise" https://preprod.signicat.com/oidc/token ``` ```text title="UserInfo endpoint for Enterprise" https://preprod.signicat.com/oidc/userinfo ``` ```text title="Discovery endpoint for new platform" https:///auth/open/.well-known/openid-configuration ``` ```text title="Authorization endpoint for new platform" https:///auth/open/connect/authorize ``` ```text title="Token endpoint for new platform" https:///auth/open/connect/token ``` ```text title="UserInfo endpoint for new platform" https:///auth/open/connect/userinfo ``` #### Request examples You can find an example of how an OIDC authentication request differs between Enterprise and our new platform below: ```text title="Example: Enterprise OIDC authentication request" https://preprod.signicat.com/oidc/authorize ?client_id= &response_type=code &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &scope=openid%20profile%20signicat.national_id &acr_values=urn%3Asignicat%3Aoidc%3Amethod%3Anbid &state= &nonce= ``` ```text title="Example: New platform OIDC authentication request" https:///auth/open/connect/authorize ?client_id= &response_type=code &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &scope=openid%20profile%20nin &acr_values=idp%3Anbid &state= &nonce= ``` :::details How to find the scoping code You can see the scoping code for your eIDs at **Signicat Dashboard** > **Products** > **eID and Wallet Hub**, > [**eIDs**](https://dashboard.signicat.com/bca/authn). For a full list of codes, visit the [eID scoping codes](/docs/eid-hub/concepts/idp-scoping/#eid-scoping-codes) table. ::: ## 6. Test in sandbox You need to test the complete authentication flow from your application in sandbox. To do this, you must confirm that: - The application starts authentication through the domain for new platform. - The end-user is routed to the correct eID method. - Authentication completes successfully. - The end-user returns to the correct redirect URI. - The application exchanges the Authorization code successfully. - The expected claims are returned. - The application can read `nin` where it would previously parse `signicat.national_id` . - Cancellation and failed authentication are handled correctly. :::warning Important For sandbox, you should only use test identities and test data. ::: ## 7. Create and configure production After sandbox testing is complete, you can create and configure the production account. :::tip Tip Production follows the same configuration process as in the sandbox account. However, all domains, credentials, endpoints and eID configurations are production-specific and must be configured accordingly. ::: 1. Open or create your production account in the [Signicat Dashboard](https://dashboard.signicat.com). - If you already have one, then you need to select it from the dropdown menu in the top navigation bar. - If you do not have one, then you need to create one using the steps below. :::details How to create a production account To create a production account, follow the steps below: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt). 2. Click the **+ Add account** button. 3. In the **Organisation** field, ensure that the correct organisation is shown. 4. In the **Account name** field, enter a name for your production account. 5. Select the **Production account** option. 6. Click the **Create** button. **Note**: If the production account option is unavailable, then you need to complete your company's contact information. To do this, click the **Complete information** link, then add the following key contacts: - Commercial owner - Main technical contact - Financial contact ::: 2. Once the production account is available, repeat steps 2-5 of this guide, but using production-specific values instead: - Configure a standard or custom production domain. - Create the same connection type used in sandbox. - Configure the production redirect URIs, scopes, and other required settings. - Generate and securely store the new production credentials. - Request that your Migration Manager configures the production eIDs. - Update the application with the production configuration. :::note Production domain suffix A standard production domain uses the `.app.signicat.com` suffix instead of `.sandbox.signicat.com`. ::: ## 8. Complete production testing and cutover After your Migration Manager confirms that the production eIDs are ready, you need to do the following: 1. Update your application with the production configuration for our new platform. 2. Run a controlled production authentication test. 3. Verify the redirect and returned claims. ### Cutover checklist Before switching all traffic, ensure that: - The production connection is configured. - The required eIDs are configured and verified by your Migration Manager. - Production testing has passed. - A rollback plan is available. :::warning Important Keep the Enterprise configuration available until the production integration for our new platform has been confirmed as stable. ::: ## Common issues For a list of common issues and potential fixes, see the table below: | **Issue** | **What to check** | | :-- | :-- | | An eID works in sandbox but not in production | Ask your migration manager whether production activation, certificates, or additional configuration are still required. | | The end-user sees an eID-selection screen instead of going directly to the eID landing page. | Verify the ACR values for our new platform. **Example**: `acr_values=idp:nbid`. | | The national identity number is missing. | Confirm that the required scope is requested, and that the application reads `nin`. | | Authentication fails with the new client. | Check that the application is not mixing sandbox and production domains, client IDs, secrets, or endpoints. | ## Next steps To learn about changes specific to the eIDs that you are using, make a selection using the buttons below: * [**Changes for Norwegian BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/nbid): Learn about migration changes specific to Norwegian BankID * [**Changes for Swedish BankID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/sbid): Learn about migration changes specific to Swedish BankID * [**Changes for MitID**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/mitid): Learn about migration changes specific to MitID * [**Changes for Finnish Trust Network (FTN)**](/docs/eid-hub/migration-guides/enterprise/changes-for-eids/ftn): Learn about migration changes specific to Finnish Trust Network (FTN) ## Related documentation To learn about related topics, make a selection using the buttons below: ### Signicat Dashboard * [**Signicat Dashboard documentation**](/docs/): Learn about the Signicat Dashboard * [**Domains**](/docs/dashboard/organisation-management/domains/): Learn how to add and manage standard Signicat domains and custom domains * [**Company registration**](/docs/dashboard/organisation-management/company-registration/): Learn how to complete the company registration process ### Protocol-specific information * [**Changes for OIDC**](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc/): Learn about migration changes specific to OIDC * [**OIDC**](/docs/eid-hub/oidc/): Learn about the OIDC authentication protocol * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Learn about the Signicat Authentication REST API authentication protocol * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Learn about the SAML 2.0 authentication protocol --- ## Migration guides Our migration guides provide you with step-by-step instructions for migrating your existing integrations to our new Signicat Digital Trust Platform (DTP). They also highlight the key differences between the old and new platforms, to help ensure a smooth transition. To get started, choose your current integration type using the buttons below: * [**Migrate from Enterprise to DTP**](/docs/eid-hub/migration-guides/enterprise/): Learn how to migrate from Signicat Enterprise to our Digital Trust Platform (DTP) * [**Migrate from Identity Broker to DTP**](/docs/eid-hub/migration-guides/signicat-identity-broker/): Learn how to migrate from Signicat Identity Broker to our Digital Trust Platform (DTP) --- ## Identity Broker to Digital Trust Platform (DTP) If you are a new customer or have recently migrated to our new platform, you can now use our existing Signicat Identity Broker solutions on our new Digital Trust Platform (DTP). :::tip Our recommendation For an introduction to the differences between the two platforms, we recommend that you start by reading our [Migrating to the new platform](https://developer.signicat.com/broker/signicat-identity-broker/migration-guide.html) guide. ::: * [**OpenID Connect migration guide**](/docs/eid-hub/migration-guides/signicat-identity-broker/migration-guide-oidc): Migrate from Signicat Identity Broker to our new Digital Trust Platform * [**SAML 2.0 migration guide**](/docs/eid-hub/migration-guides/signicat-identity-broker/migration-guide-saml): Migrate from Signicat Identity Broker to our new Digital Trust Platform --- ## OpenID Connect migration guide As the world of digital identity is constantly evolving, we wanted to provide an even better experience for our customers using the Signicat Identity Broker. That's why we built our new Digital Trust Platform. The new platform is designed to simplify how you integrate and how you can use other Signicat products, while providing secure, reliable and developer-friendly services to meet your digital identity goals. On this page, you can find information about the differences between the two platforms when implementing OpenID Connect (OIDC) connections. In the new platform, you can create and setup connections similarly to how you used to but a few aspects have changed. Learn more about these upgrades below. :::info Migrating from Signicat Identity Broker: An introduction For an introduction to the differences between the two platforms, we recommend you start with our [Migrating to the new platform](https://developer.signicat.com/broker/signicat-identity-broker/migration-guide.html) guide. ::: ## How it works In the new platform, referred to as the Signicat Dashboard, you can manage end-user login and authentication through the **eID and Wallet Hub**. This product gives you access to a hub of European eIDs through a single point of integration which supports a range of authentication protocols, such as SAML 2.0 and OIDC. :::tip Getting started After the migration, you might want to discover how the new Signicat Dashboard works. To get started, consider the following guides: - [Introduction to the Signicat Dashboard](/docs/dashboard/) - [Quick start guide for the eID and Wallet Hub](/docs/eid-hub/quick-start/index.mdx) - [How to set up new OIDC connections](/docs/eid-hub/oidc/oidc-client/) ::: ### Migrating to the eID and Wallet Hub When you migrate from the Signicat Identity Broker to the eID and Wallet Hub, all your existing connections have already been automatically migrated and are ready to use. We refer to these connections as **legacy connections**. :::info Where can I find legacy connections? To manage your previous OIDC connections that have been migrated to the Signicat Dashboard, go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > **Legacy** > [**Legacy connections**](https://dashboard.signicat.com/bca/oidc). ::: Note that you can also create new OIDC connections in the new Signicat Dashboard. The difference between new and legacy connections is that legacy connections still support legacy options to provide you with an environment similar to the Signicat Identity Broker. ## What's changed :::note Documentation coming soon If you want to migrate to the new platform, contact us for more information and technical documentation: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: --- ## SAML 2.0 migration guide As the world of digital identity is constantly evolving, we wanted to provide an even better experience for our customers using the Signicat Identity Broker. That's why we built our new Digital Trust Platform. The new platform is designed to simplify how you integrate and how you can use other Signicat products, while providing secure, reliable and developer-friendly services to meet your digital identity goals. On this page, you can find information about the differences between the two platforms when implementing SAML 2.0 connections. In the new platform, you can create and setup connections similarly to how you used to but a few aspects have changed. Learn more about these upgrades below. :::info Migrating from Signicat Identity Broker: An introduction For an introduction to the differences between the two platforms, we recommend you start with our [Migrating to the new platform](https://developer.signicat.com/broker/signicat-identity-broker/migration-guide.html) guide. ::: ## How it works In the new platform, referred to as the Signicat Dashboard, you can manage end-user login and authentication through the **eID and Wallet Hub**. This product gives you access to a hub of European eIDs through a single point of integration which supports a range of authentication protocols, such as SAML 2.0 and OIDC. :::tip Getting started After the migration, you might want to discover how the new Signicat Dashboard works. To get started, consider the following guides: - [Introduction to the Signicat Dashboard](/docs/dashboard/) - [Quick start guide for the eID and Wallet Hub](/docs/eid-hub/quick-start/index.mdx) - [How to set up new SAML 2.0 connections](/docs/eid-hub/saml-2-0/saml-metadata.mdx) ::: ### Migrating to the eID and Wallet Hub When you migrate from the Signicat Identity Broker to the eID and Wallet Hub, all your existing connections have already been automatically migrated and are ready to use. We refer to these connections as **legacy connections**. :::info Where can I find legacy connections? To manage your previous SAML 2.0 connections that have been migrated to the Signicat Dashboard, go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > **Legacy** > [**Legacy connections**](https://dashboard.signicat.com/bca/oidc). ::: Note that you can also create new SAML 2.0 connections in the new Signicat Dashboard. The difference between new and legacy connections is that legacy connections still support legacy options to provide you with an environment similar to the Signicat Identity Broker. You can learn more about these changes in the next section below. ## What's changed When implementing a connection with SAML 2.0 in the new platform, note that the following properties have changed: - [SAML Metadata](#saml-metadata) - [Subject and NameID](#subject-and-nameid) - [Attribute naming](#attribute-naming) You can find more information about these changes below. ### SAML Metadata We have changed two feature of the SAML Metadata, namely: - The Metadata URL - The `IDPSSODescriptor` endpoints #### New Metadata URL Our new platform introduces a new Metadata URL path: :::CustomTable | Property | Old Metadata URL endpoint | New Metadata URL endpoint | | :------------|:----------------------------------------------|:--------------| | Metadata URL | `https://*YOUR_SIGNICAT_DOMAIN*/broker/sp/saml/metadata`| `https://*YOUR_SIGNICAT_DOMAIN*/auth/saml/metadata` | | Path | `/broker/sp/saml/metadata` | `/auth/saml/metadata` | ::: :::info Updating the Metadata URL You can still use the old metadata URL in the early stages of migration. This is fully supported. However, we recommend you update your applications to use the new Metadata URL. ::: #### IDPSSODescriptor The new Metadata URL endpoint affects the endpoints in the `Location` attribute of the `IDPSSODescriptor` object: ```xml title="Example: Metadata New Platform eID and Wallet Hub" ``` ```xml title="Example: Metadata Signicat Identity Broker" ``` ### Subject and NameID :::tip Subject attribute You can learn more about the subject in the [Concepts > Subject](/docs/eid-hub/concepts/subject/) page. ::: In the Signicat Identity Broker, you used to receive the subject attribute through `NameID` according to SAML 2.0 specifications. This attribute contained the raw/unhashed subject by default. In the new Signicat eID and Wallet Hub, this has changed so that `NameID` returns the **hashed** subject in the SAML response instead. In your legacy connection you can revert this and receive the raw/unhashed subject instead. You can view examples of how this has changed, below: When end-users authenticated with DigiD in the Signicat Identity Broker, you used to receive the raw subject (for example, the BSN `900026236`) in the response: ```xml {4} title="Before: DigiD reponse example in the Signicat Identity Broker" 900026236 ``` After migrating to the Signicat eID and Wallet Hub, `NameID` provides the **hashed** subject: ```xml {4} title="After: DigiD reponse example in the Signicat eID and Wallet Hub" a94a8fe5ccb19ba61c4c0873d391e987982fbbd3 ``` To learn more about the data you can obtain with DigiD, see the DigiD [Attributes reference](/identity-methods/digid/attribute-reference/). When end-users authenticated with eHerkenning in the Signicat Identity Broker, you used to receive the raw subject in the response: ```xml {5} title="Before: eHerkenning reponse example in the Signicat Identity Broker" ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890 ``` After migrating to the Signicat eID and Wallet Hub, `NameID` provides the **hashed** subject: ```xml {5} title="After: eHerkenning reponse example in the Signicat eID and Wallet Hub" k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y= ``` To learn more about what values eHerkenning returns as subject, see the `idpId` description in the eHerkenning [Attribute glossary](/identity-methods/eherkenning/attributes-reference/glossary/#idpid). When end-users authenticated with iDIN in the Signicat Identity Broker, you used to receive the raw subject, the [Bank Identification Number (BIN)](/identity-methods/idin/attributes-reference/#bank-identification-number-bin), in the response: ```xml {5} title="Before: iDIN reponse example in the Signicat Identity Broker" NLRABOtestdata8de3695d048d9da76b7c09d5a800b51897441e8ae3210731a058e ``` After migrating to the Signicat eID and Wallet Hub, `NameID` provides the **hashed** subject: ```xml {5} title="After: iDIN reponse example in the Signicat eID and Wallet Hub" Cf-jk2TjFLNaZ2rEMDjuz6YUecBKQrfCJbHgNPPQBnI= ``` To learn more about the data you can obtain with iDIN, see the iDIN [Attributes reference](/identity-methods/idin/attributes-reference/). #### How to receive the raw subject If you prefer to still receive the raw/unhashed subject after the migration, you can choose to either: - Configure the raw subject for `NameID` - Request `idpId` Find out more about each option below. ##### Configure the raw subject for NameID :::note Only for legacy connections Note that you can configure the unhashed subject through `NameID` *only* for legacy connections, which have been migrated from the Signicat Identity Broker to the eID and Wallet Hub. This option is not available for new connections. ::: To configure your SAML 2.0 legacy connection to still return the unhashed subject through `NameID`, do the following: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com/). 2. Navigate to **Products** > **eID and Wallet Hub** > **Legacy** > [**Legacy connections**](https://dashboard.signicat.com/bca/oidc). 3. Select the SAML 2.0 legacy connection you intend to edit. 4. In the connection page, navigate to the **Advanced** tab. 5. In the Advanced tab, tick `Send unhashed subject in the response`. 6. Click **Save** at the bottom to save the changes. :::note Option not available If the `Send unhashed subject in the response` checkbox is not available in your SAML 2.0 legacy connection configuration in the Signicat Dashboard, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ##### Request idpId To receive the raw/unhashed subject in the response, you can request it as an additional attribute by specifying the `idpId` field in the `RequestedAttribute` element of your SAML authentication request. For more details, see the [SAML Request Attributes](/docs/eid-hub/saml-2-0/saml-requested-attributes/) guide. When requesting the `idpId` field, you receive the unhashed subject in the `AttributeStatement` element in the response. This applies for both legacy and new SAML 2.0 connections. ```xml {4,11} title="DigiD reponse example in the eID and Wallet Hub with idpId" a94a8fe5ccb19ba61c4c0873d391e987982fbbd3 ... 900026236 ``` :::tip Alternative: Request the `nin` With DigiD you can receive the raw subject (BSN) also when requesting the `nin` attribute. Learn more about the data you can obtain with DigiD in the [Attributes reference](/identity-methods/digid/attribute-reference/). ::: ```xml {5,12} title="eHerkenning reponse example in the eID and Wallet Hub with idpId" k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y= ... ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890 ``` ```xml {5,12} title="iDIN reponse example in the eID and Wallet Hub with idpId" Cf-jk2TjFLNaZ2rEMDjuz6YUecBKQrfCJbHgNPPQBnI= ... NLRABOtestdata8de3695d048d9da76b7c09d5a800b51897441e8ae3210731a058e ``` ### Attribute naming The new platform introduces new naming for all the attributes. The new names are shorter, more intuitive and ensure consistency across eIDs. This means that you need to update how you define personal data fields in your authentication request. #### Attribute name changes Expand the sections below to reveal the respective table for each eID: :::details iDIN attribute name changes (Click to expand) :::CustomTable | Legacy Attribute Name | New Attribute Name | | --- | --- | | `urn:nl:bvn:bankid:1.0:consumer.18orolder` | `18OrOlder` | | `urn:nl:bvn:bankid:1.0:consumer.bin` | `bin` | | `urn:nl:bvn:bankid:1.0:consumer.city` | `address.city` | | `urn:nl:bvn:bankid:1.0:consumer.country` | `address.country` | | `urn:nl:bvn:bankid:1.0:consumer.dateofbirth` | `dateOfBirth` | | `urn:nl:bvn:bankid:1.0:consumer.email` | `email` | | `urn:nl:bvn:bankid:1.0:consumer.gender` | `gender` | | `urn:nl:bvn:bankid:1.0:consumer.houseno` | `address.houseNumber` | | `urn:nl:bvn:bankid:1.0:consumer.housenosuf` | `address.houseNumber AND address.houseNumberSuffix` | | `urn:nl:bvn:bankid:1.0:consumer.initials` | `initials AND name.firstName` | | `urn:nl:bvn:bankid:1.0:consumer.legallastname` | `legalLastName` | | `urn:nl:bvn:bankid:1.0:consumer.legallastname` | `name.lastName` | | `urn:nl:bvn:bankid:1.0:consumer.legallastnameprefix` | `legalLastNamePrefix` | | `urn:nl:bvn:bankid:1.0:consumer.partnerlastname` | `partnerLastName` | | `urn:nl:bvn:bankid:1.0:consumer.partnerlastnameprefix` | `partnerLastNamePrefix` | | `urn:nl:bvn:bankid:1.0:consumer.postalcode` | `address.postalCode` | | `urn:nl:bvn:bankid:1.0:consumer.preferredlastname` | `preferredLastName` | | `urn:nl:bvn:bankid:1.0:consumer.preferredlastnameprefix` | `preferredLastNamePrefix` | | `urn:nl:bvn:bankid:1.0:consumer.street` | `address.street` | | `urn:nl:bvn:bankid:1.0:consumer.telephone` | `phoneNumber` | ::: :::details eHerkenning attribute name changes (Click to expand) :::CustomTable | Legacy Attribute Name | New Attribute Name | | --- | --- | | `urn:etoegang:1.11:attribute-represented:AddressArea` | `organisationAddressArea` | | `urn:etoegang:1.11:attribute-represented:AdminunitFirstline` | `organisationCountryCode` | | `urn:etoegang:1.11:attribute-represented:AdminunitSecondline` | `organisationRegion` | | `urn:etoegang:1.11:attribute-represented:ChamberOfCommerce` | `chamberOfCommerce` | | `urn:etoegang:1.11:attribute-represented:CompanyName` | `organisationName` | | `urn:etoegang:1.11:attribute-represented:EORI` | `organisationEori` | | `urn:etoegang:1.11:attribute-represented:KvKnr` | `organisationKvkNr` | | `urn:etoegang:1.11:attribute-represented:LEI` | `organisationLegalEntityIdentifier` | | `urn:etoegang:1.11:attribute-represented:LocatorDesignator` | `organisationLocatorDesignator` | | `urn:etoegang:1.11:attribute-represented:LocatorName` | `organisationLocatorName` | | `urn:etoegang:1.11:attribute-represented:POBox` | `organisationPoBox` | | `urn:etoegang:1.11:attribute-represented:PostName` | `organisationCity` | | `urn:etoegang:1.11:attribute-represented:SEED` | `organisationSeed` | | `urn:etoegang:1.11:attribute-represented:SIC` | `organisationSic` | | `urn:etoegang:1.11:attribute-represented:TaxReferenceNumber` | `organisationTaxReferenceNumber` | | `urn:etoegang:1.11:attribute-represented:Thoroughfare` | `organisationStreetName` | | `urn:etoegang:1.11:attribute-represented:VATRegistrationNumber` | `organisationVatRegistrationNumber` | | `urn:etoegang:1.11:attribute:BirthName` | `birthName` | | `urn:etoegang:1.11:attribute:non-transliterated:FamilyName` | `eherkenningLastNameNonTransliterated` | | `urn:etoegang:1.11:attribute:non-transliterated:FamilyNameAtBirth` | `eherkenningLastNameAtBirth` | | `urn:etoegang:1.11:attribute:non-transliterated:FirstName` | `eherkenningFirstNameNonTransliterated` | | `urn:etoegang:1.11:attribute:non-transliterated:FirstNameAtBirth` | `eherkenningFirstNameAtBirth` | | `urn:etoegang:1.12:EntityConcernedID:PseudoID` | `eherkenningPseudoID` | | `urn:etoegang:1.13:attribute-intermediate:CompanyName` | `eherkenningIntermediateOrganisationName` | | `urn:etoegang:1.13:EntityConcernedID:Pseudo` | `eherkenningPseudo` | | `urn:etoegang:1.13:IntermediateEntityID:TRR-BD` | `eherkenningIntermediateTrrBd` | | `urn:etoegang:1.9:attribute-represented:HouseNumber` | `organisationHouseNumber` | | `urn:etoegang:1.9:attribute-represented:HouseNumberSuffix` | `organisationHouseNumberSuffix` | | `urn:etoegang:1.9:attribute-represented:PostalCode` | `organisationPostalCode` | | `urn:etoegang:1.9:attribute:12OrOlder` | `12OrOlder` | | `urn:etoegang:1.9:attribute:16OrOlder` | `16OrOlder` | | `urn:etoegang:1.9:attribute:18OrOlder` | `18OrOlder` | | `urn:etoegang:1.9:attribute:65OrOlder` | `65OrOlder` | | `urn:etoegang:1.9:attribute:FamilyNameInfix` | `familyNameInfix` | | `urn:etoegang:1.9:attribute:Initials` | `initials` | | `urn:etoegang:1.9:attribute:PlaceOfBirth` | `placeOfBirth` | | `urn:etoegang:1.9:EntityConcernedID:KvKnr` | `chamberOfCommerce` | | `urn:etoegang:1.9:EntityConcernedID:RSIN` | `eherkenningRsin` | | `urn:etoegang:1.9:IntermediateEntityID:KvKnr` | `eherkenningIntermediateKvkNr` | | `urn:etoegang:1.9:ServiceRestriction:Vestigingsnr` | `eherkenningVestigingsNr` | | `urn:etoegang:core:ServiceID` | `eherkenningServiceID` | | `urn:etoegang:core:ServiceUUID` | `eherkenningServiceUUID` | ::: #### Use legacy attribute naming for iDIN, eHerkenning and DigiD :::note Important This option applies only to attributes in the *response* object. This means that you need to use the new attribute names in the authentication *request*. ::: In the eID and Wallet Hub, you can configure your legacy SAML connection to return attributes with the legacy naming in the response, as you used to receive them in the Signicat Identity Broker. For example, this option allows you to receive `urn:nl:bvn:bankid:1.0:consumer.bin` instead of `bin` from authentications with iDIN. This means that you receive data points that follow the original naming instead of the new attribute names. To enable legacy attribute naming in your legacy connections, do the following: 1. Log in to the [Signicat Dashboard](https://dashboard.signicat.com/). 2. Navigate to **Products** > **eID and Wallet Hub** > **Legacy** > [**Legacy connections**](https://dashboard.signicat.com/bca/oidc). 3. Select the SAML 2.0 legacy connection you intend to edit. 4. In the connection page, navigate to the **Advanced** tab. 5. In the Advanced tab, tick `Use legacy attribute naming for iDIN, eHerkenning and DigiD`. 6. Click **Save** at the bottom to save the changes. :::warning DigiD: Exception If you enable the `Use legacy attribute naming for iDIN, eHerkenning and DigiD` for your connection to DigiD and request `nin`, the authentication response will only contain legacy attribute. Therefore, `nin` is not provided in the response object since it is a new attribute introduced in the eID and Wallet Hub. However, you can still receive the BSN (what `nin` returns) through a separate attribute like `idpId`. ::: :::info Option not available If the `Use legacy attribute naming for iDIN, eHerkenning and DigiD` checkbox is not available in your SAML 2.0 connection configuration in the Signicat Dashboard, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Example responses Below, you can find examples of responses from different eIDs with comparisons between the responses you used to obtain from Signicat Identity Broker and the new responses in the Signicat eID and Wallet Hub. ### Signicat Identity Broker ```xml title="DigiD reponse example in the Signicat Identity Broker" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... 900234854 https://*SP_CLIENT_DOMAIN*/saml 900234854 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport https://was-preprod1.digid.nl/saml/idp/metadata ``` ```xml title="eHerkenning reponse example in the Signicat Identity Broker" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 https://*SP_CLIENT_DOMAIN*/saml 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 52035476 850272038 urn:etoegang:DV:00000003244440010000:services:9121 cf1c1457-cc97-4b47-a324-25d1a97db3cb 24444001 email@example.com Gerarda Josephina Kierkegaard 1928-12-09 represented company name intermediary company name 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:00000003520354760000:entities:9713 ``` ```xml title="iDIN reponse example in the Signicat Identity Broker" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... FANTASYBANK1234567890 https://*SP_CLIENT_DOMAIN*/saml de info@equensworldline.nl Vries-Jansen Jansen 19750725 DE 1 VJ +31203051900 de Vries Pascalstreet 19 0000AA Aachen de FANTASYBANK1234567890 urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard idin ``` ### Signicat eID and Wallet Hub ```xml title="DigiD reponse example in the eID and Wallet Hub" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... s0VCNNq9aysShPBhbD1LnyHTmtuK9v789e6ST1sD-Pc= https://*SP_CLIENT_DOMAIN*/saml 900234854 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport https://was-preprod1.digid.nl/saml/idp/metadata ``` ```xml title="eHerkenning reponse example in the eID and Wallet Hub" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... MfNtm-LbN8Qxi0b9wT-wAZ31QwwV5FHkh-iAnzqrVWY= https://*SP_CLIENT_DOMAIN*/saml Gerarda Josephina Kierkegaard Gerarda Josephina Kierkegaard 1928-12-09 email@example.com 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 52035476 850272038 urn:etoegang:DV:00000003244440010000:services:9121 cf1c1457-cc97-4b47-a324-25d1a97db3cb 24444001 represented company name intermediary company name 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:00000003520354760000:entities:9713 ``` ```xml title="iDIN reponse example in the eID and Wallet Hub" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... Cf-jk2TjFLNaZ2rEMDjuz6YUecBKQrfCJbHgNPPQBnI= https://*SP_CLIENT_DOMAIN*/saml de Vries-Jansen Jansen VJ de Vries de VJ de Vries VJ de Vries 1975-07-25 info@equensworldline.nl 1 Pascalstreet 19, 0000AA, Aachen, DE Pascalstreet 19 Aachen 0000AA DE +31203051900 FANTASYBANK1234567890 urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard idin ``` --- ## Client authentication with Private Key JWT When requesting tokens you can use a signed assertion as authentication instead of the basic authentication with a client ID and client secret pair. In Private Key JWT your application creates and signs a JWT using a private key. Private Key JWT is a client authentication method that is more secure than the default “Client Secret” method. Note that Private Key JWT involves additional steps on your end. ## Prerequisites Before configuring an application that authenticates using Private Key JWT, you must generate an RSA key pair. You can choose between: - Import the public part of an existing key pair into the Signicat Dashboard, or - Generate an RSA key pair directly in the Signicat Dashboard. #### Import the public key If you wish to generate your own key pair, make sure you meet these technical requirements: 1. Generate a JWK RSA key pair (2048-bit) suitable for encryption. We also support 4096-bit if required. It is important that you create a JWK or an X509 certificate. We recommend using the JWK format. 2. Store the **public part** of your key pair in a text file (or `.json`). If you chose to create your own key pair, then in the next section click **Import public key** instead of **Add public key** in step 2. #### Generate the key pair To generate a key pair in the Signicat Dashboard: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select the client you wish to use. If you haven't created a client yet, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the client menu, navigate to **Advanced** > **Public keys** and then **Add public key**. 4. Fill in the **Name**, **Not valid before** and **Not valid after** fields for your key. 5. Select **Signing** as the **Usage**. 6. Now press **Create**. If you want to upload your public key, either paste your key content or upload a file with the key. 7. A key pair is generated for you. This contains a public key and a private key. Take a copy of the private key and store it somewhere safe. You are now ready to move on to the implementation. ## Implementation :::note Before you continue Private Key JWT modifies how your application sends the **token endpoint request**, therefore this section assumes that you first start an OIDC authentication request as for any client authentication method. Before you continue, your application should have already completed these steps: - Start an OIDC authentication request. - Authenticate the end-user. - Receive an authorization code on your chosen redirect URI. After these steps, the Private Key JWT implementation below applies. ::: Authenticating using Private Key JWT consists of two steps: 1. Building the assertion. This is a JWT signed by the private key that you generated. 2. Exchanging the assertion for an access token to authenticate with Signicat. ### Step 1. Building the assertion Begin by crafting an assertion in the form of a JSON Web Token (JWT). :::details What is a JWT? A JSON Web Token (JWT) consists of three parts separated by dots (`.`), which correspond to: - Header - Payload - Signature A JWT typically looks like: `xxxxx.yyyyy.zzzzz` ::: The payload of the JWT should contain the following valid claims: :::CustomTable{columnWidths="15% 15%"} | Claim | Name | Details | |:------|:-----------|:-----------------------------------| | `iss` | Issuer | The client ID of your OIDC client. | | `sub` | Subject ID | The client ID of your OIDC client. | | `aud` | Audience | Must match your 'Token URL'. To find this value, see your [**OIDC client**](https://dashboard.signicat.com/oidc-clients/) in the Dashboard. | | `jti` | JWT ID | The unique identifier for the JWT. Mitigates replay attacks. | | `iat` | Issued At | The UNIX timestamp (in seconds) of when you created the token. | | `exp` | Expire | The UNIX timestamp (in seconds) of when your token will no longer be valid. We recommend `now + 10 minutes`. | ::: An example of JWT payload would look like: ```json { "iss": "", "sub": "", "aud": "https:///auth/open/connect/token", "jti": , "iat": 1673955575, "exp": 1673961575, } ``` Now, create a signed JWT using a payload similar to the one above. Serialise this as a compact format JWT. The serialised JWT is a long string that looks like: `eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA` #### Code example In the example below, the Python script shows how to generate the assertion: ```python from time import time from uuid import uuid4 from jwcrypto import jwk, jws # For the sake of simplicity, the JWKs has been manually loaded into a dictionary. # In a real life scenario you should do this in a secure manner: The jws_private_key should be stored securely on your premise. jws_private_key = { "kty": "RSA", "kid": "my-kid-123", "use": "sig", "alg": "RS256", "e": "AQAB", "n": "2sZ0sfbK7bZWOZgAYGWvEkL-9HWt-UadCKRyZHgIRNxvS1KdNZE4chcXF7sXfuAim6Ec_WbcEqGTOzOmQF-VejluB6jO-banEKl3pTGxRj2xj5tBFbtpWyj_AENHxpzbb7EPR_ahIPyvQeCU3VFOEw8juVd9X3gn_iJdmxbN7yIWzhuMRimAleT04AR8SP-g9NUauaEZSrIwny_JbeZ_Fb1m2XfPTB8KbbnYPeyQTQRy_2H5vMLRYGhOFyF9DS_6TguJlSc2VdPLsfW_uhbS4X1fd8-RVbF8UJ6lSanOhmIw1Choh_ncy90-tmmsk6T2QPKBwY0UqgU6bAv5iD2pdw", "d": "eRHSipn0-1Aor3661p3vIMAKr-Zf_M9jH-FBnPAAQ3tp69kwPvC6uAinMu7Ktd_7xvyGOoWtzHG2NNEEdCNxaU5W4c49nFvEYKgoGjdBz4lctghJIGmyiExLsi2JjxRHK6xktIJ78PFlW6OZPlE8T7fVIUCVlTu9hhomiyk3ldnVjrwJ5ESzaJs_zh6dqNcbfP-8APbG74ACejG3ojp9DWadOwA6kDtKIGdBAHZxObDJtG8qKQDcqvrxBUDXkifl-7t3b97HhxMRyR-d6wvrmz5mkYEzNZJt6LYkCyeGkE-IoQmPM0qYiWI7F3H4E1YjCoGlueoAQCoGOkFCMLYMQQ", "p": "8_fKHLlwG_t57jsYG97ggGiYnFV9P6FMU3xe6dptMMrqhuPl_XbMic8CA-vOVP_nTgxDfaEnv_wlGcYgVLwdlIICjvoLB1Fma4SguAVCloIZbYsiXBwpfXiTWn-RgSe1HtTbfzpmBpt4RJiHEPoWx34ZUDZhcSpREuO2sIG_U18", "q": "5ZCYsdA2yJmGJ_quksnNVIa8cby_a_SfFKg_5-CYSKyoZFaZttaNL064f0DCCO4tEp31W37_SankFUkdMDN8ccyW6xwnOj3PJRTX2J79sXdKaJDGleEXCKzuF7Rbi0nouP-1YFxjRmRh5WjBRDvbyCc-m_1ofxbwRskw3CPiOOk", "dp": "GU9YoXg_gDero6Jv0txhcBDp3DYmQ0apk3OwqRQnBcvXXt0fzBbaC2X1cJCzHDBcP8WX7t2cMReoha7_RasqanC-cTTRlhXEyVy-C7lH-jNPDgVEMEgfqcurhdT8NGj5KlSs3NsjIIZaiMtGH-XCHTogyCiMHWBlfs8u8crUHYM", "dq": "WiqSHv0mF2JdlCRdHyCOOo31REMbeH6LYSS4fQ31Ik5WkZqGI49fwt4Lj0fTLojGQVKzhS17feZxxH6ELWN7lIMEH_Jd4f1W-DyYjufbwzGUkz-SEFppnqm1lq_raOkttEQTbHa9M2_IF8AucOuF5rarW7-LpKdQ1qy9OSoK98k", "qi": "rR6CplTi8roFIPwTes4puAABvN-agWh6jRxVVll1SfjqBFoTQvBHp8bUhJO7zmAEhOh-oDQX5Prn24CDKu_kr7emD-WeF9qaGJG1Gltrnh_-nj2XWpfMFmeJWOcflAWJPeltRn3f9PUrnujMDHNDg4EsD8f-ckzPOldqTH_zF_Y" } # Loading key rsa_jws_private_key = jwk.JWK() rsa_jws_private_key.import_key(**jws_private_key) # Token payload (JSON) payload = { "iss": "", "sub": "", "aud": "https:///auth/open/connect/token", "jti": str(uuid4()), "iat": int(time()), "exp": int(time()+6000), } payload_bytes = json.dumps(payload).encode('utf-8') # Token headers jws_header = { "alg": jws_private_key["alg"], "kid": jws_private_key["kid"], } # Creating JWS token jwstoken = jws.JWS(payload_bytes) jwstoken.add_signature(rsa_jws_private_key, protected=jws_header) jws_serialized = jwstoken.serialize(compact=True) print(f"JWT: '{jws_serialized}'") ``` :::warning Important This code example is for illustrative purposes only. It is not intended for production usage. Signicat takes no responsibility if this code example is used inappropriately. ::: ### Step 2. Exchanging the assertion After you build and sign the JWT with the required claims, you are ready to authenticate your application to receive an access token. Use the signed JWT as your assertion towards Signicat token endpoint. For example, ``` client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer client_assertion={JWT} ``` The HTTP request would be: ```curl curl --request POST https://api.signicat.com/auth/open/connect/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=authorization_code' \ --data 'scope=openid+profile' \ --data 'code={CODE}' \ --data 'redirect_uri=https%3A%2F%2Fyourdomain.com%2Fredirect' \ --data 'client_id={OIDC_CLIENT_ID}' \ --data 'client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer' --data 'client_assertion={JWT}' ``` Note that the response you receive back is the same as from any other token endpoint request. --- ## Advanced security considerations Below you can find guides to advanced techniques to increase the security of your OIDC implementation. * [**Proof Key for Code Exchange (PKCE)**](/docs/eid-hub/oidc/advanced-security/proof-key-for-code-exchange-pkce): Add PKCE to your OIDC flows * [**Private Key JWT**](/docs/eid-hub/oidc/advanced-security/client-authentication-with-private-key-jwt): Authenticate by signing a JWT with a private key * [**Pushed Authorization Requests (PAR)**](/docs/eid-hub/oidc/advanced-security/pushed-authorization-requests-par): Protect your authorization parameters with PAR * [**Encryption/signing of the request object**](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests): Send signed and encrypted requests to Signicat * [**Encrypted/signed responses**](/docs/eid-hub/oidc/advanced-security/receive-encrypted-signed-responses): Receive encrypted/signed responses from Signicat --- ## Proof Key for Code Exchange (PKCE) :::tip Use PKCE PKCE helps you prevent CSRF and authorization code injection attacks. We recommend that you always use PKCE as it is useful for every type of OAuth client, even web apps that use client authentication. ::: ## Add PKCE in your request To use PKCE in your request, you need to specify a `code_challenge` and `code_challenge_method` in the authentication URL. ``` https:///auth/open/connect/authorize? &client_id= &response_type=code &redirect_uri= &state=1725028142040-3nB &scope=openid%20profile &code_challenge=tkeeeeUcqFyZCFRfM35wERUWdfo8iFWnIM6F-7ILmXw &code_challenge_method=S256 &prompt=login ``` To use PKCE, your application should create a cryptographically-random `code_verifier` and from this generate a `code_challenge`. Most OIDC libraries support PKCE. Code libraries and snippets can also help with implementing PKCE. See [oauth.net: PKCE](https://oauth.net/2/pkce/) for further details. ## How to enforce PKCE in the Dashboard Optionally, you can configure your OIDC client to always require PKCE. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Choose the OIDC client and select **Edit**. If you haven't created a client yet, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the **Advanced > Security** tab, tick the **Requires PKCE** box. **Note**: The client now requires PKCE in every authorization request. Requests without using PKCE will fail. --- ## Pushed Authorization Requests (PAR) Pushed Authorization Requests (PAR) is an extension for OpenID Connect and OAuth, as detailed in [https://datatracker.ietf.org/doc/html/rfc9126](https://datatracker.ietf.org/doc/html/rfc9126). PAR has the following advantages: - Mitigates issues caused by exceeding the max URL length or passing too many and/or too long URL request parameters in your request. When using PAR, you only include a short `request_uri` parameter as a reference. - Improves security, similarly to [Encryption/signing of the request object](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests.mdx), but in a simpler and more elegant fashion. With PAR, you prevent the end-users (or bad actors) from seeing or tampering with the URL request parameters. ## How PAR works To use PAR in your OIDC application, you need to: 1. Send a backend request (with the request parameters) to the PAR endpoint. You receive the `request_uri` in the response. 3. Then, change your requests to the `authorize` endpoint to include the `request_uri` parameter, instead of passing URL request parameters. When using PAR, you specify the payload of the authorization request in the first request to the `par` endpoint. Then, you pass only the reference to the `request_uri` in the request to the `authorize` endpoint. ## Prerequisites There is no additional configuration to use PAR on a per-request basis. ### How to enforce PAR in the Dashboard :::tip PAR is always available If you want to use PAR only on a per-request basis, you may skip this step. ::: Optionally, you can configure your OIDC client to always require PAR. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Choose the OIDC client and select **Edit**. If you haven't created a client yet, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the **Advanced > Security** tab, tick the **Requires Pushed Authorization Requests (PAR)** box. **Note**: The client now requires PAR in every authorization request. Requests without using PAR will fail. ## Implementation Implementing PAR changes your typical OIDC flow in the following way: 1. You must make a backend call to the PAR endpoint, _before_ you make the request to the `authorize` endpoint. 2. Then, in the request to the `authorize` endpoint include only the `request_uri` (and the required parameters `client_id` and `response_type`), instead of including all the normal URL parameters. ### Step 1. Perform Pushed Authorization Requests :::warning Send the request from the backend It is important that you send the PAR request from the backend of your application. Sending the request from the frontend, or any insecure environments, exposes your client secret. ::: You find the PAR endpoint at `https:///auth/open/connect/par`. For example, `https://example.signicat.com/auth/open/connect/par`. The HTTP request would be: ```http POST /auth/open/connect/par HTTP/2 Host: example.signicat.com Authorization: Basic c2FuZGJveC1zaGlueS1oYXQtMTkxOlVTSnlZMEFsRG1IZkx3cUV6SFp6a2RXZ0tCYUNwS1BNcnRybjZPcVdueERtRjZLOA== Content-Type: application/x-www-form-urlencoded Content-Length: 1000 client_id=&response_type=code&redirect_uri=code&scope=openid+profile+nin&prompt=login&state=1724229949354-Dyf&nonce=1725006273399-5Ca ``` Note how you should include the payload with all query parameters, such as `scope` and `prompt`, in the request to the PAR endpoint. In return, you obtain the `request_uri` in the response from the PAR endpoint. Example success response: ```http HTTP/2 201 Created Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "request_uri": "urn:ietf:params:oauth:request_uri:851358EAA07A23B315AFC00B1EAA9C34C6C4B04A2DA4B598D455CF1F62E004EB", "expires_in": 600 } ``` You receive the `request_uri` in the response from the PAR endpoint. Use the value of the `request_uri` in the subsequent request to the `authorize` endpoint. :::note Combine PAR with Private Key JWT Note that you can combine PAR with [Private Key JWT client authentication](/docs/eid-hub/oidc/advanced-security/client-authentication-with-private-key-jwt.mdx). ::: ### Step 2. OIDC Authorize request Now, use the `request_uri` in your `authorize` request, without including the URL request parameters. Example authorization request: ``` https:///auth/open/connect/authorize? &client_id= &response_type=code &request_uri=urn:ietf:params:oauth:request_uri:851358EAA07A23B315AFC00B1EAA9C34C6C4B04A2DA4B598D455CF1F62E004EB ``` The above are the only changes you need for using PAR. Now, you may continue your OIDC flow as normal. To learn more about implementing OIDC flows, see the [OIDC implementation](/docs/eid-hub/oidc/oidc-implementation.mdx) documentation. --- ## Encrypted/signed responses from Signicat As per OIDC specification, Signicat can send encrypted responses. This means we always encrypt the ID tokens and `UserInfo` responses for a given OIDC client. Responses from Signicat are fully encrypted on the transport layer with HTTPS, but adding message-level encryption can be used as an additional security layer. This section explains how to set up and process encrypted responses. :::warning Finnish Trust Network (FTN) For FTN you are required to receive encrypted responses. In fact, FTN fails if you do not set this up correctly and you are not able to obtain any FTN authentication results. ::: ### Prerequisites Typically you don't need to create your own keys, as you can generate key pairs in the Signicat Dashboard. If you do want to fully manage your own keys, you need to first generate one and then import it and store it in the Signicat Dashboard, from where we can fetch it. If you wish to create your own key pair, these are the technical requirements: 1. Generate a JWK RSA key pair (2048-bit) suitable for encryption. We also support 4096-bit if required. It is important that you create a JWK or an X509 certificate. We recommend using the JWK format. 2. Store the **public part** of your key pair in a text file (typically `.json`). :::note Bringing you own key pair If you choose to create your own key pair, then in the next section select **Import public key** instead of **Add public key**. ::: ### Required configuration 1. In the Signicat Dashboard, go to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select your OIDC client. To create a new OIDC client, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the client menu, go to **Advanced** > **Public keys** and select **Add public key**. Instead, select **Import public key** if you want to import your own key. 4. Fill in the **Name**, **Not valid before** and **Not valid after** fields for your key. 5. Select **Encryption** as the **Usage**. 6. Now, select **Create**. 7. A key pair is generated for you. This contains a public key and a private key. Take a copy of the private key and store it somewhere safe. You now have an encryption key that we can use to encrypt the responses we send to you, and that you should be able to decrypt. Finally, you need to configure the encryption on your client: 1. In the Signicat Dashboard, go to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). Then, select again your OIDC client. 2. In the menu for the client, select **Advanced** > **Security**. 3. Under **User Info Response Type** select **SignedAndEncrypted**. (If you prefer you can also select **Encrypted**, which is out of scope for this guide.) 4. Enable **Encrypt ID Tokens**. You are now ready to continue to the implementation. ### Implementation You should send your requests as normal OIDC requests, since what changes are the responses you receive from Signicat. The ID token and the response from `UserInfo` is a nested JWT which is encrypted and signed. To process it: 1. Decrypt it with your private key from the key pair provided in the Signicat Dashboard. 2. Deserialise the resulting signed JWT and verify it, as you would do with a normal token. ### Code example :::warning Important This code example is for illustrative purposes only. It is not intended for production usage. Signicat takes no responsibility if this code example is used inappropriately. ::: ```python from jwcrypto import jwk, jwe # ATTENTION: Insert your nested JWT (that you got from Signicat OIDC server) here!!! jwe_serialized = "eyJh...QifQ.Qq5TQR...xN-PQ.ojSGehTV7xw_xE078sFnTg.in8a...SITqA.SyVNrXe0C3UkKBQ_AVyQiw" # For the sake of simplicity, the JWKs has been manually loaded into a dictionary. # In a real life scenario you should do this in a secure manner: The jwe_private_key should be stored securely on your premise. jwe_private_key = { "alg": "RSA-OAEP", "d": "MODJkQVnKx-txB11QSkz2roacDL9z-BqcDq-dYM2OHrI-x4iNpdBWtoS2Hi4OfH6ETmzMnFNVY3oIYoaMTuuWKc0r_QeIIqbkt8MozALusETiB2VtiAiiZU6G2DyAOFaWaoiIlRYO5BciDCM6z4ytfnDFYM7-K-YSA3_V7jDSGjRroGC112lVs9BzA3qjCP8jnb9VvNKUhdcFqsqGU8eRw8fZp73uHyEm9tVHimSPjyLda3XlcxPSEkhqlP4aaleWhkUQJM3bc2YDnpWBjlNuIHsacEA28xrwOqHSqK-b8klvxk-e_w-C-SdlcYhgB5DeSB0bEuCpmV9GKwOp0KhuQ", "dp": "hkPXP00qlIrioShp3FiXp0_OahJXe4cVNAXLJYgKRsqv72I7AXZltAOXNRanpQDQutDADFsMTx1XxoEQm_GUvTUe-dS-PkBGKJMLjp28zs9G0L4yXUXenKu_vs-3wD4_06WtT_kOyJD48LaQno6SYdUm4JBvS5A1ve2NYI7xDEk", "dq": "WGmNHsCzREbHgwQCStW9munP16NJzdeXJ0ys7QbLwpOxMEP1BkSznoRw4_0IkSxTtyvWPG9Eo-bPCKfkqILUowG7tniIerf0F6LkCjssPk5wNxEK_Ktt-59_3Wrvs9Iik4tYF0bEqlXyidFq7ayBoRdiPZ0-ELjU-hEqY0GR0Ok", "e": "AQAB", "kid": "mykey-123", "kty": "RSA", "n": "zOeJ1RJOgP6NlgwEcqa-BtHUC5nNNa2UbsQQsNDQa6KioVcNfiz5WWmQF3FAR7HTAxQveXfgT7PqOmPgiDVHTLcdYlOjcOAESCTFYELsuh58xnA99agM9vPuLVo2x-hwjE_b-1dC3Ph2_gpXwqS6JDjKa5VF-5zMLbVLQJ96yhKGqzQ7TrfXrEcgfzXMipTbQTxpDAFnTyYYQ7lOVp_ms0Kbz4fpRbyGUtzYsgkYBCNwfWgtfXZW7ahMeb84ukbH2nXXQKQsxuSYU-gbK44yVvcvltqg5wMjG39Xo-BUGlJGQzEN0-6QEIqGrMXgTx5B147IV22vT7demmNx2_RXDQ", "p": "-3lVxpmyecuu7-tceX7eoVjHmUlbHzUkhehkV_axQx5FtX5NRWdzqg8jhmPBBRpMtvG7g55ZQihVTi3sphfP0k1czEPsgJt8diZ4KIMDgimcksyJ8yPP0dZuvdnBVFVdlJDWfimmLxmFwlmw-p3gCAPePbqRjD1vo25Bwi5Dujk", "q": "0JeicVX3YgVhUXuY_f3BX-VDKR0LH_SLaIaEimuvpleo5AM4El_An8SR-_Z1GXZuzsOvff7d_E79NjwsdhtKKxQiW93awsFD9Fd5fqNUOpB0ikAf-gNz6MCujt9nhS_jvbMsNI6gCRexZ4gD-RB9dj_qXsWWJUJQpcu7QMmeE3U", "qi": "-MNE31_wnD2aRLiZz0piLD6lHJwSYpGFinBKWp5VPuLdeXAruSdKW82oRTapA-y6s87fB85jcjvW3dAYjzFFsFNpjDzrpCwctIsQVzZt_vVu5Mdon365tFHWyH2xAcTmVxdJGDunR6BKMmnciCdXTgZP8wSAEWrjmVop_ontfM8", "use": "enc" } # Loading JWK key jwk_jwe_private_key = jwk.JWK() jwk_jwe_private_key.import_key(**jwe_private_key) jwetoken = jwe.JWE() jwetoken.deserialize(jwe_serialized) jwetoken.decrypt(jwk_jwe_private_key) jws_serialized = jwetoken.payload print("\nSIGNED JWT (just like a normal ID token):\n") print(jwetoken.payload) ``` --- ## Encryption/signing of the request object As per OIDC specification, you can use the (optional) `request` parameter to enable signed and, additionally, encrypted requests. Though not required, using the `request` parameter provides additional security and helps you comply with any Full Message-Level Encryption (MLE) requirements. Common scenarios for using encrypted/signed requests include masking personal information contained in the request and sending requests that cannot be tampered with by third parties. ### Additional hardening of request object mechanism You can harden the security of your requests in two ways: 1. Require request object 2. Unique/One-Time-Use request object These options are discussed below. #### Require request object You can configure your OIDC clients to require the request object in any future request. To do this: 1. In the Signicat Dashboard, go to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select your OIDC client. To create an OIDC client, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the OIDC client menu, go to **Advanced** > **Security** and tick **Requires Request Object** to enable it. After you enable the **Requires Request Object**, all future requests with this OIDC client will require a request object. Requests without a request object will fail. Effectively, this setting forces all requests on the OIDC client to be at least signed. #### Unique/One-Time-Use request object If you submit a request object token that contains the `jti` claim, we will ensure that it is unique for this client within 24 hours. This will work automatically without additional configuration required. If you do not wish to have unique request objects enforced, simply omit the `jti` claim. This mechanism can effectively prevent “replay attacks” when using request objects, as each request object token can only be used once. ### Types of request objects The Signicat OIDC solution accepts two types of request objects: 1. **Signed JWT**: A valid JWS token. 2. **Nested JWT**: A token that is first signed (JWS) and then encrypted (JWE). :::note Encryption keys To encrypt your nested JWT, you must use one of our public encryption keys, available at: [https://api.signicat.com/auth/open/.well-known/openid-configuration/jwks](https://api.signicat.com/auth/open/.well-known/openid-configuration/jwks). You can retrieve encryption keys at any time. Encryption keys have the following properties: - Always contain `"use": "enc"`. - `"kid"` (key id) starts with `encryption-key`. For sandbox accounts, the `kid` starts with `sandbox-encryption-key`. ::: :::warning Key rotation When using our public encryption keys, you must account for key rotation. A key is available for max 39 days, and on occasion even shorter. To ensure that you always have a valid key, we recommend that you refresh your cache within 7 days. ::: ### Prerequisites Before configuring an application that authenticates using nested JWTs, you must generate an RSA key pair. To do this, you can either: - Import the public part of an existing key pair into the Signicat Dashboard, or - Generate an RSA key pair directly in the Signicat Dashboard. #### Import the public key If you wish to generate your own key pair, make sure you meet these technical requirements: 1. Generate a JWK RSA key pair (2048-bit) suitable for encryption. We also support 4096-bit if required. It is important that you create a JWK or an X509 certificate. We recommend using the JWK format. 2. Store the **public part** of your key pair in a text file (or `.json`). If you chose to create your own key pair, then in the next section click **Import public key** instead of **Add public key** in step 2. #### Generate the key pair To generate a key pair in the Signicat Dashboard: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select the client you wish to use. If you haven't created a client yet, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). 3. In the client menu, navigate to **Advanced** > **Public keys** and then **Add public key**. 4. Fill in the **Name**, **Not valid before** and **Not valid after** fields for your key. 5. Select **Signing** as the **Usage**. 6. Now press **Create**. If you want to upload your public key, either paste your key content or upload a file with the key. 7. A key pair is generated for you. This contains a public key and a private key. Take a copy of the private key and store it somewhere safe. You are now ready to move on to the implementation. ### Implementation Begin crafting the OIDC authorisation request. The parameters are standard OIDC parameters. The requirements are as follows: - The HTTP request can be made using either GET or POST. - The payload must be a request object, following the [OIDC Core specifications, section 6.1](https://openid.net/specs/openid-connect-core-1_0.html#RequestObject)). An example of a typical payload request object looks as follows: ```json { "client_id": "dev-annoyed-sloth-492", "response_type": "code", "redirect_uri": "https://oauth.tools/callback/code", "acr_values": "idp:ftn", "state": "ABCDEF012345", "scope": "openid profile", "iss": "dev-annoyed-sloth-492", "aud": "https://team-connect-demo.test.signicat.dev/auth/open", "iat": 1673955575, "exp": 1673961575, } ``` Note that the JWT requires the following additional claims to be valid: :::CustomTable{columnWidths="25% 75%"} | Claim | Explanation | |:------|:-----------------------------------| | `iss` | Issuer - needs to be the same as your `client_id`. | | `aud` | Audience - needs to be equal to your 'Issuer URL'. (Check your client on the [Dashboard](https://dashboard.signicat.com) to find it.) | | `iat` | Issued At - A UNIX timestamp (in seconds) for the time at which you created the token. | | `exp` | Expire - A UNIX timestamp (in seconds) for the time at which your token will no longer be valid. We recommend `now + 10 minutes`. | ::: **Steps:** 1. Create a signed JWT using a payload similar to the one above. Serialise this as a compact format JWT. The serialised JWT is a long string. 2. Now, create an encrypted JWT using the serialised signed JWT from above as the payload. This should again be serialised as a compact format JWT. 3. Use this nested JWT as your request object towards Signicat. For example, `/auth/open/connect/authorize?client_id={CLIENT_ID}&request={REQUEST_OBJECT_JWT}`. ### Code example :::warning Important This code example is for illustrative purposes only. It is not intended for production usage. Signicat takes no responsibility if this code example is used inappropriately. ::: ```python from time import time from jwcrypto import jwk, jwe, jws # For the sake of simplicity, the JWKs has been manually loaded into a dictionary. # In a real life scenario you should do this in a secure manner: The jws_private_key should be stored securely on your premise. # The jwe_public_key should be dynamically fetched from Signicat's JWKS endpoint. jws_private_key = { "alg": "RS256", "d": "IfHsADmK2xsxbie2Q4pX5cOEfWEeD8efIC82_PtK7AT-ZO3vwll9WUQ_VMWXZuUkmDDwuLukp-GCAq871YfsJKTEXYibArYZSB6yPo7FHMxtEtsfOqDGEjCJHd76AE99ZH8qA2H_0j_xGMGbAP44x5DoTAidj1B3fKEF_IQfoHNfvQBwLaE2lyJVxQp_Xzay_VbdeGRlacmzc8ccGWU3lpAYDONMPxh0Z9tx2aexarDOjFbZ0jKN9b9-Hyntnz7iOFdiOWSHo41NOd5l2BG4SARdRPUwoMxcEexxVVPjpr1smNwLHJZdAvOMiHSAKDAwKh4Vgu4p5CfD6O6JM_PoSQ", "dp": "TSi83Xlf9XP9DMeqCQgMXUcrxt4nSh56C0RnqRPneGShlObkUZmxJoaEh5TL5OJ-9MQKcGCBN0_LOFls1p4NOvdhZxxwHi2hEZisdd40IY37Z-4JN0L5Xs4jqLDrZAP_paEW1SOI33sqhHCeLi034DZw0-4BxKXm5Fhn-uS2WZ8", "dq": "jSvo3MsPzigQN_20txhQFxqQaw6M7udXgt51QW50tnM896DlpEd0hbcryOncpfc8AVhjyxLnGG2sYQRLswcq838STu4wDEhuPfhgKAak_5cc38N_TSyRJWLfnwF9pTTWPgkk0Io8MwWpsIpf9qIbyBOl0jHnBdfSuuLKoYM6QfU", "e": "AQAB", "kid": "abc123321cba", "kty": "RSA", "n": "muNJBpq6VtZbGj0kb5YeMe5lE14CZ4OAKnY6Epzholp61rVrrWRlErmyV9C8J4G6jCgDKrGnjQp143gD71ATVLIus__wO1YtRplKCyz2hypvhvId8GwYOLm1k3TCjKeSa6DwKiKZZOUg011NWN9TSSkCdWb-xNgSV5gZesC_JngofTyrAXT92MDIzGoCMpA1D6tDIzadIigHA7_FznpT1eN5cAHZqMeRC8MHRH2_K8erUxx4QFuencrADmaf4vIWjTlmPioxa4XLRrYcXsnKrrKeVp8CXRFqMwb0fAtRmvQu3RHUqZ02dlTER7ocIbrHeYx2_VAxhqFtLhR9J2ih0w", "p": "zpfR9mwYoPB-r1wTy5owD8RaoufPeVnabefe7IK9nwGUOkgINHDGTRPvXx2f0UuKz9kAVB6ZIsPgwCfhoMrbdQemNLXu5VZ_MRny6Uesk_5Awox5QIBbYvzF6PnMfV-pwLtieNLpiN_sP-pF6jfvJ8cy3XFBUnF5IDy0zeuI4Lc", "q": "v-3u72-IPZpVuY8hkqi8gPpc5FTSWh-MJ5BvOcifDFjVYEE-KCTL5I2MJ2R9u-1sVceeFwfa-HfgV3ArizO91-pSJSqk-Py3KqHDXXdno30wwwJWR8noSwH8eRwqdQHBQQPa0ClywQJ2bbqiiw30CpjXDHknL5qXQEskpoJq88U", "qi": "SGo4PyG344Uxddy_g_YGTt5pa_lvq0G42jGWU-fOPQfjSiNWhzuyflys9YoSf_x3kzwf1oJosdUdCpfUXzLX1LHsWrUld-52JFPtuFT3nNVZiFXCnboUHJSIlgaP1GlA1rHhh491gMIPqr4uJY3BSKp7aj2efL61Z-1l-LvwrSw", "use": "sig" } jwe_public_key = { "kty": "RSA", "use": "enc", "kid": "sandbox-encryption-key-0eb954d0e12b824b80a3c5664232320a", "e": "AQAB", "n": "trU6figprTeSBBTdW7Lqm6OjgNg4neNSvtEUs__bf5iK59W9oH2oeZLPx7ixmuJ3Cane6WHCR4BumxtnoIixWlNAJgdu_xosI-zO_7fhUVIgS-qH5kY9rj8GUa6GUquAV92_L3nnEWgKJ_220jV8_kdaqab1Pm5QMJ9RSC73BWuvCZ5fWb57okFN5-dTtjZ-WCmgij-9axPKjlM0PTp4c8Lm8KJDO-B-6n8DO9JEfdBpa6ejEIGi3tNJAyveluTzZ5YyF_WFD4rJZ2JIJIuGth7-o1Myq5QhmaXBTrL01aY-bLgiqWrtBNpM2rnU3MMUQn0TOpzKVvRaTl-x5HIpvw", "alg": "RSA-OAEP" } # Loading keys jwk_jws_private_key = jwk.JWK() jwk_jws_private_key.import_key(**jws_private_key) jwk_jwe_public_key = jwk.JWK() jwk_jwe_public_key.import_key(**jwe_public_key) # Token payload (JSON) payload = { "client_id": "dev-annoyed-sloth-492", "response_type": "code", "redirect_uri": "https://oauth.tools/callback/code", "state": "ABCDEF012345", "scope": "openid profile", "iss": "dev-annoyed-sloth-492", "aud": "https://team-connect-demo.test.signicat.dev/auth/open", "iat": int(time()), "exp": int(time()+6000), } payload_bytes = json.dumps(payload).encode('utf-8') # Token headers jws_header = { "alg": jws_private_key["alg"], "kid": jws_private_key["kid"], } jwe_header = { "alg": jwe_public_key["alg"], "enc": "A128CBC-HS256", "kid": jwe_public_key["kid"], } # Creating JWS token jwstoken = jws.JWS(payload_bytes) jwstoken.add_signature(jwk_jws_private_key, protected=jws_header) jws_serialized = jwstoken.serialize(compact=True) # Encoding JWE token jwetoken = jwe.JWE(jws_serialized, recipient=jwk_jwe_public_key, protected=jwe_header) jwe_serialized = jwetoken.serialize(compact=True) print(f"https://team-connect-demo.test.signicat.dev/auth/open/connect/authorize?client_id={payload['client_id']}&request={jwe_serialized}") ``` #### Detailed tutorial and code example For an even more detailed description of how to set this up, including code examples, see the [Signed and encrypted tokens](/docs/eid-hub/oidc/code-examples/signed-and-encrypted-tokens.mdx) code example. --- ## CIBA (OIDC extension) ## About CIBA OpenID Connect CIBA ([Client Initiated Backchannel Authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-final.html)) is an extension of the OpenID Connect protocol that allows the client application to initiate the authentication process and receive real-time updates on the authentication status. ## Differences between CIBA and the authorization code flow The [authorization code flow](/docs/eid-hub/oidc/oidc-implementation.mdx#authorization-code-flow) and the CIBA flow are two different authentication flows in the OpenID Connect protocol. #### Authorization code flow In an authorization code flow: - The client application redirects the user to the authorisation server, where the user logs in and provides consent. - After successful authentication, the authorisation server redirects the user back to the client application with an authorization code. - The client application then exchanges this code for an access token and a refresh token by making a direct request to the authorization server's token endpoint. :::tip When to choose it This flow is primarily designed for web applications and requires user interaction during the entire authentication process. ::: #### CIBA flow The CIBA flow introduces a more flexible and asynchronous approach to authentication. In a CIBA flow: - The client application initiates the authentication process by making a backchannel authentication request to the authorization server. - The server responds with a unique authentication reference. - The client can then receive real-time updates on the authentication status by polling the token endpoint. :::tip When to choose it This flow is particularly useful in scenarios when: - The client application may not have a user interface, or - The client application needs to authenticate the user on a different device, or - You want to create a completely customised login flow with complete control over the UI in a web application or a mobile app (similar to the Authentication REST API [headless flow](/docs/eid-hub/authentication-api/#headless-flow)). ::: ## Application flow A successful CIBA flow follows the following pattern: 1. The client makes a call to the `backchannel_authentication_endpoint`, indicating in the `acr_values` parameter which eID is being used and possibly passing other parameters applicable for that eID. 2. The client then proceeds to polling the `token_endpoint` which will answer with `authorization_pending` until the end-user has completed the authentication, at which point the usual token response is returned, containing `id_token` and `access_token`. 3. The client may then optionally use the `access_token` to call the `UserInfo` endpoint if needed, or skip this step if the `id_token` already contains the required information. :::tip More details in the OIDC official documentation - [Backchannel request parameters](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-final.html#rfc.section.7.1) Note that not all parameters are supported by all eIDs. - [Possible responses from the token endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-final.html#rfc.section.11). ::: ## Setting up an OIDC client for CIBA To create an OIDC client for CIBA: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Create/Add client**. 3. Set the **Primary grant type** to "Ciba". 4. Enter a name for the client. 5. Add the OIDC scopes specific for your integration. Ciba OIDC client After that, you add a secret to your client and then perform any additional configuration you would like to do. ## eIDs that support CIBA You can use the buttons below to explore the current list of eIDs that support CIBA. * [**Swedish BankID**](/identity-methods/sbid/): Learn more about Swedish BankID * [**MobileID**](/identity-methods/mobileid/): Learn more about MobileID * [**Norwegian BankID**](/identity-methods/nbid/): Learn more about Norwegian BankID ## Example using Swedish BankID ### The backchannel endpoint The discovery metadata of your domain with Signicat contains the URL of the `backchannel_authentication_endpoint`. For example, if your domain with Signicat is `yourdomain` then the discovery metadata is available at `https://yourdomain.signicat.com/auth/open/.well-known/openid-configuration` where the `backchannel_authentication_endpoint` is `https://yourdomain.signicat.com/auth/open/connect/ciba`. The call to the CIBA endpoint should be an HTTP POST request with content-type `application/x-www-form-urlencoded`. Make sure to authenticate the request with Basic authentication and the following parameters: - `login_hint = endUserIp:127.0.0.1 flow:QR` (`127.0.0.1` is an example. Replace it with the actual public IP address of the end-user.) - `acr_values = idp:sbid` - `scope = openid profile nin` The HTTP request could look like this: ```http POST /auth/open/connect/ciba HTTP/1.1 Authorization: Basic ZGV2LW...CamdraTd2 Host: yourdomain.signicat.com Content-Type: application/x-www-form-urlencoded Content-Length: 100 login_hint=endUserIp%3A127.0.0.1%20flow%3AQR&acr_values=idp%3Asbid&scope=openid%20profile%20nin ``` And the response would look like (some headers omitted for brevity): ```http HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "auth_req_id": "5ddc7357-abe0-6940-b4a3-fd6eb3277830", "expires_in": 120, "interval": 1 } ``` To obtain the `autoStartToken` for `APP_LAUNCH` or the data for the `QR` code flow, your application must request it from the token endpoint as described in the following section. ### The token endpoint From this point on, the flow consists of polling the token endpoint. To do that, we perform HTTP POST calls to the token endpoint with the following parameters - `auth_req_id = 5ddc7357-abe0-6940-b4a3-fd6eb3277830` (The `auth_req_id` received in the previous response.) - `grant_type = urn:openid:params:grant-type:ciba` An example of HTTP request would look like this: ```http POST /auth/open/connect/token HTTP/1.1 Authorization: Basic ZGV2LW...CamdraTd2 Host: yourdomain.signicat.com Content-Type: application/x-www-form-urlencoded Content-Length: 101 auth_req_id=8c65e7e5-f5cc-1b4c-a3f5-9f81985ccc83&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba ``` And the response would be (some headers omitted for brevity): ```http HTTP/1.1 400 Bad Request content-type: application/json; charset=UTF-8 { "error": "authorization_pending", "error_description": "bankid.584e5929-0d9e-4dc7-9890-921f...f252b", "error_uri": "https://yourdomain.signicat.com/auth/open/config/errors/authorization_pending" } ``` - In the `APP_LAUNCH` flow, the `error_description` contains an `autoStartToken`. You can use this to construct the app launch URL. The `autoStartToken` will remain the same for the duration of the session. - In the `QR` code flow, the `error_description` contains the data you need to generate a QR code for the user to scan. :::warning Animated QR code Swedish BankID uses an “animated QR code” security feature, which means that a QR code is only valid for a short time (seconds). This means your application must generate a new QR code for each call to the token endpoint and continuously update the QR code displayed to the end-user. In such scenarios, a polling interval of 1-2 seconds is recommended. ::: Your client should continue to poll the endpoint as long as the response is an HTTP 400 with `error` equal to `authorization_pending`. The token endpoint will respond like this: - If the user cancels the process, the response will be an HTTP 400 with error `access_denied`. - If the user takes too long to complete the process, the response will be an HTTP 400 with error `expired_token`. - If the user has still not fully completed the authentication, the response will be an HTTP 400 with error `authorization_pending`. - And when the user has successfully completed the process, the response will be an HTTP 200 with the usual token response, including `id_token` and `access_token`. ### Code example The following is a simplistic Python example of a function that first calls the backchannel endpoint and then makes one call to the token endpoint: ```python def ciba(end_user_ip, flow='QR'): # First the backchannel call url = base_url + '/auth/open/connect/ciba' headers = { 'Authorization': 'Basic ZGV2LWNs...amdraTd2', 'Content-Type': 'application/x-www-form-urlencoded' } data = { 'login_hint': 'endUserIp:' + end_user_ip + ' flow:' + flow, 'acr_values': 'idp:sbid', 'scope': 'openid profile' } http_response = requests.post(url, headers=headers, data=data) ciba_response = json.loads(http_response.content) print(json.dumps(ciba_response, indent=4)) # And then the token endpoint call url = base_url + '/auth/open/connect/token' data = { 'auth_req_id': ciba_response['auth_req_id'], 'grant_type': 'urn:openid:params:grant-type:ciba' } http_response = requests.post(url, headers=headers, data=data) token_response = json.loads(http_response.content) print(json.dumps(token_response, indent=4)) ``` Running the function produces the following output: ```json { "auth_req_id": "9761e8e8-a38b-2e40-a7bd-730805ef9e70", "expires_in": 120, "interval": 1 } { "error": "authorization_pending", "error_description": "bankid.3a047f6a-5e7b-41...8faf1db5e892", "error_uri": "https://yourdomain.signicat.com/auth/open/config/errors/authorization_pending" } ``` ### A note about the flow options In the example above, we exclusively used the `QR` flow. The other option is the `APP_LAUNCH` flow which – instead of the BankID QR code data - returns the `autostarttoken` from Swedish BankID that you can use to launch the BankID app in “same-device” scenarios. For more information, visit [https://www.bankid.com/en/utvecklare/guider/teknisk-integrationsguide/programstart](https://www.bankid.com/en/utvecklare/guider/teknisk-integrationsguide/programstart). --- ## Authorization code flow (Basic) This guide is designed to get you started with your integration for end-user authentication. The guide is written for .NET using C# and covers the basics of setting up an authorization code flow. Learn more about OIDC grant types in the [OIDC implementation](/docs/eid-hub/oidc/) documentation. ## How it works In an authorization code flow: - The client application redirects the user to the authorisation server, where the user logs in and provides consent. - After successful authentication, the authorisation server redirects the user back to the client application with an authorization code. - The client application then exchanges this code for an access token and a refresh token by making a direct request to the authorization server's token endpoint. OpenID Connect flow diagram :::tip When to choose the Authorization code flow The Authorization code flow is primarily designed for web applications and requires user interaction during the entire authentication process. ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: This guide assumes you already have installed and properly configured the following in your local machine: - [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.1). - A code editor, such as [Visual Studio Code](https://code.visualstudio.com/), [Visual Studio](https://visualstudio.microsoft.com/vs/) or [Rider](https://www.jetbrains.com/rider/). - A command-line interface, such as [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell). All commands in this guide were tested with PowerShell. Additionally, we strongly recommend you use a library or framework for the implementation, such as the ones provided by [JWT](https://jwt.io/libraries). ## Create an OIDC client Make sure your OIDC client has been properly created and configured. To do this in the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). You can find the required client settings below. :::details Client settings on the Dashboard - Information - Name: **_filled_** - URI: _empty_ - Logo URI: _empty_ - URIs - Redirect URI: **_filled with 1 (one) URI_** - For example: _https://localhost:5001/account/callback_ - Post logout redirect URI: _empty_ - Front channel logout URI: _empty_ - Front channel logout session required: **_false_** - Security - Primary grant type: **_Authorisation code_** - Require secret: **_true_** - Require PKCE: **_true_** - Allow access token via browser: **_false_** - User reference access tokens: **_false_** - Allowed CORS origins: _empty_ - Encrypt ID tokens: **_false_** - User info response type: _empty (or default)_ - Content encryption algorithm: _empty (or default)_ - Accesses - Allowed scopes: **_filled with, at least, `openid` and `profile`_** - Identity provider restrictions: _empty_ - Lifetimes - All fields with default values ::: :::warning Add a secret After saving your client, you must generate a new secret. ::: ## Tutorial steps ### 1. Initialise your project Start your solution: ```shell mkdir SignicatQuickStartGuide cd .\SignicatQuickStartGuide\ dotnet new sln ``` Add an empty web project: ```shell dotnet new web --name AuthorizationCodeFlowGuide dotnet sln .\SignicatQuickStartGuide.sln add .\AuthorizationCodeFlowGuide\ ``` ### 2. Install dependencies Add support to OpenID Connect authentication workflow by including the following package in your project: ```shell dotnet add .\AuthorizationCodeFlowGuide\ package Microsoft.AspNetCore.Authentication.OpenIdConnect --version 3.1.7 ``` ### 3. Startup settings Under the `Startup` class, do the following. Set `using` statements: ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Threading; using System.Threading.Tasks; using Microsoft.AspNetCore.Authentication.OpenIdConnect; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.IdentityModel.Protocols.OpenIdConnect; ``` Create an asynchronous method to redeem the authorisation code for tokens at token endpoint: ```csharp protected virtual async Task RedeemAuthorizationCodeAsync(AuthorizationCodeReceivedContext context) { var configuration = await context.Options.ConfigurationManager.GetConfigurationAsync(CancellationToken.None); var requestMessage = new HttpRequestMessage(HttpMethod.Post, configuration.TokenEndpoint); var authInfo = $"{context.TokenEndpointRequest.ClientId}:{context.TokenEndpointRequest.ClientSecret}"; authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo)); requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Basic", authInfo); var tokenEndpointRequest = context.TokenEndpointRequest.Clone(); tokenEndpointRequest.ClientSecret = null; requestMessage.Content = new FormUrlEncodedContent(tokenEndpointRequest.Parameters); var responseMessage = await context.Backchannel.SendAsync(requestMessage); if (!responseMessage.IsSuccessStatusCode) { Console.WriteLine(await responseMessage.Content.ReadAsStringAsync()); return; } try { var responseContent = await responseMessage.Content.ReadAsStringAsync(); var message = new OpenIdConnectMessage(responseContent); context.HandleCodeRedemption(message); } catch (Exception exc) { Console.WriteLine($"An error occurred: {exc.Message}"); } } ``` Register authentication and controller with views services in the `ConfigureServices` method: :::tip Value for config.Authority Your value for `config.Authority` will vary depending on your configuration. - If you haven't configured a custom domain: in the code sample below, replace `chosen-name` with the name you have chosen for your account. - If you have configured your own custom domain, change the value of `config.Authority` to `https://your.domain.com/auth/open`. ::: ```csharp {5-35} public void ConfigureServices(IServiceCollection services) { // omitted for brevity services.AddAuthentication(config => { config.DefaultAuthenticateScheme = "AuthorizationCodeClientAppCookie"; config.DefaultSignInScheme = "AuthorizationCodeClientAppCookie"; config.DefaultChallengeScheme = "Signicat"; }) .AddCookie("AuthorizationCodeClientAppCookie") .AddOpenIdConnect("Signicat", config => { config.Events.OnAuthorizationCodeReceived = RedeemAuthorizationCodeAsync; config.Authority = "https://chosen-name.app.signicat.dev/auth/open"; config.ClientId = "YOUR_CLIENT_ID_HERE"; config.ClientSecret = "YOUR_CLIENT_SECRET_HERE"; config.CallbackPath = "/account/callback"; config.UsePkce = true; config.ResponseType = "code"; config.Scope.Add("openid"); config.Scope.Add("profile"); config.GetClaimsFromUserInfoEndpoint = true; config.SaveTokens = true; }); services.AddControllersWithViews(); // omitted for brevity } ``` Add authentication and authorisation middlewares to the pipeline and change endpoint mappings to default in the `Configure` method: ```csharp {5-11} public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { // omitted for brevity app.UseAuthentication(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapDefaultControllerRoute(); }); // omitted for brevity } ``` ### 4. Protected resource To check if everything is working as expected, create a basic controller (_HomeController_) with an Index action and a simple View to it. The folder and file structure could be similar to this: ```{6,9} . ├─ SignicatQuickStartGuide.sln ├─ AuthorizationCodeFlowGuide │ ├─ AuthorizationCodeFlowGuide.csproj │ ├─ Controllers │ │ └─ HomeController.cs │ └─ Views │ │ └─ Home │ │ └─ Index.cshtml │ └─ ... └─ ... ``` :::warning NOTE Other folders and files omitted for brevity. ::: Your **Home** _controller_ could be similar to: ```csharp using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Mvc; namespace AuthorizationCodeFlowGuide.Controllers { public class HomeController : Controller { [Authorize] public IActionResult Index() { return View(); } } } ``` Your **Index** _view_ could be similar to: ```html Index This is a protected resource! Only visible after authentication. ``` ### 5. Run Execute your project: ```shell dotnet run --project .\AuthorizationCodeFlowGuide\ ``` Open [https://localhost:5001/](https://localhost:5001/) in a browser. :::tip Use HTTPS We strongly recommend using HTTPS. ::: :::tip Port number Change your port number, if necessary. It's the same host you set on your client's redirect URI. ::: ### 6. Test end-user Choose **Norwegian BankID** and sign with a [test user](/identity-methods/nbid/test.mdx) as follows: :::CustomTable{columnWidths="33% 33% 33%"} | National identity number | One time password | Password | | :----------------------- | :---------------- | :--------- | | `01100844350` | `otp` | `qwer1234` | ::: {/* ## Source code You can find the complete **quick start guide** source code available for *.NET Core 3.1* on [Signicat's GitHub repo](https://github.com/signicat/Quick-start-guide-Authentication-.NET-Core). (hiding because this is for Green stack)*/} --- ## Code examples Below you can find tutorials with code examples to help you set up your integration with OIDC. :::tip Just getting started? If you are new to the Signicat eID and Wallet Hub, start your journey with the [Quick start](/docs/eid-hub/quick-start/index.mdx) guide. ::: ## Basics * [**Authorization code flow**](/docs/eid-hub/oidc/code-examples/authorization-code-flow): Set up authentication with the Authorization code flow ## Advanced * [**Signed and encrypted tokens**](/docs/eid-hub/oidc/code-examples/signed-and-encrypted-tokens): Sign and encrypt request objects, ID tokens and UserInfo --- ## Signed and encrypted tokens (Advanced) This end-to-end tutorial shows how to set up and use signing and encryption for request objects, ID tokens and UserInfo. The programming language is C# in an ASP.NET web application. In the below code examples, we will use the domain name `docs.sandbox.signicat.com`. :::note Note This is a low-level tutorial. Most middleware or abstractions for OIDC integrations allow you to send and consume encrypted and signed objects and tokens using configuration options rather than writing the type of code displayed in this tutorial. ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: This quick start guide assumes you already have installed and properly configured the following in your local machine: - [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.1). - A code editor, such as [Visual Studio Code](https://code.visualstudio.com/), [Visual Studio](https://visualstudio.microsoft.com/vs/), or [Rider](https://www.jetbrains.com/rider/). - A command-line interface, such as [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7). All commands in this guide were tested with PowerShell. Additionally, we strongly recommend you use a library or framework for the implementation, such as the ones provided by [JWT](https://jwt.io/libraries). ## Basic setup 1. Create a new OIDC client and a secret for it, as illustrated in the following screenshots. Create a new OIDC client: Create new OIDC client with signature and encryption Add a secret: Add secret 2. To be able to test it, add the redirect URI `https://oauth.tools/callback/code` to your client. This enables the **Try out this client on oauth.tools!** button on the OIDC Client Management overview page. So far, this is without any signing and encryption. This will redirect the end-user to `https://docs.sandbox.signicat.com/auth/open/connect/authorize?&client_id=sandbox-happy-root-923&response_type=code&redirect_uri=https://oauth.tools/callback/code&scope=openid%20profile&prompt=login`and then back to the redirect URI where you can redeem the authorization code for a token response with `id_token` and `access_token`, and using the `access_token` to fetch `userinfo` returns: ```json { "idp_id": "FANTASYBANK1234567890", "gender": "0", "sub": "JDAonVZOyWR-iQExci3RTHkWerjTK8DvhLa6yOr2CVc=", "idp_issuer": "simulator" } ``` ## Code example for the basic, non-signed and non-encrypted flow Redirecting the user in a .NET web application could be done as follows: ```csharp public async Task Plain() { JObject wellknown = await GetWellknown(); string authorizeUrl = wellknown["authorization_endpoint"]?.ToString() + $"?client_id={Properties.Settings.Default.ClientID}" + $"&redirect_uri={Url.Encode(RedirectUri)}" + $"&response_type=code&scope=openid%20profile&prompt=login"; return Redirect(authorizeUrl); } ``` `GetWellknown` is the utility method: ```csharp private async Task GetWellknown() { if (_wellknown == null) { string metadata = await _client.GetStringAsync(Properties.Settings.Default.DiscoveryEndpoint); _wellknown = JObject.Parse(metadata); } return _wellknown; } ``` :::tip Well-known URL Well-known configuration document path: `/auth/open/.well-known/openid-configuration` For example: `docs.sandbox.signicat.com/auth/open/.well-known/openid-configuration` You can view your Well-known URL in the [OIDC Client Overview](https://dashboard.signicat.com/oidc-clients) in the Dashboard. ::: The user would then be sent to the `authorizeUrl` for authentication, eventually returning to the `RedirectUri` where the following would take place: ```csharp public async Task Callback(string code) { string accessToken; JObject wellknown = await GetWellknown(); using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["token_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Basic", BasicAuth); httpRequest.Content = new FormUrlEncodedContent(new Dictionary { { "grant_type", "authorization_code" }, { "redirect_uri", RedirectUri }, { "code", code } }); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string responseContent = await httpResponse.Content.ReadAsStringAsync(); dynamic tokenResponse = JObject.Parse(responseContent); accessToken = tokenResponse.access_token; } using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["userinfo_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string responseContent = await httpResponse.Content.ReadAsStringAsync(); return Content(responseContent, "application/json"); } } ``` The final output could be like this: ```json { "idp_id": "FANTASYBANK1234567890", "gender": "0", "sub": "JDAonVZOyWR-iQExci3RTHkWerjTK8DvhLa6yOr2CVc=", "idp_issuer": "simulator" } ``` ## Setting up the client for message-level signing and encryption ### Signing the request object The purpose of sending signed request objects to the `authorization` endpoint is to ensure the integrity of the data sent with the end-user browser. To accomplish this, you must craft a request object signed with your own private key, and register the public counterpart of that key in the Signicat Dashboard so that it can be verified that the request is, in fact, signed by you. To do this: 1. Generate a key pair (public and private): You can generate your own key pair, or use the Signicat Dashboard to generate it for you. To do the latter, open the **Advanced** tab of your client, choose **Public keys** > **Add public key**. Enter your key name and a validity time, choose **Signing** as the purpose and click **Create**. Add public signing key Signicat will then generate the key, store the public part of the key, and also _display_ the private key for you to copy. Signicat does not store the private key, it is generated for you, for your convenience. 2. You must copy this private key and include it in your application. In the example below, the private key is placed in **Settings**. Here is an example on how you can create and sign the request object: ```csharp public async Task Signed() { // We need some info from the .well-known/openid-configuration JObject wellknown = await GetWellknown(); // We create a dictionary to hold the parameters that we would previously // put in the query string but will now go into the request object. Dictionary requestObjectParameters = new Dictionary { { "client_id", Properties.Settings.Default.ClientID }, { "redirect_uri", RedirectUri }, { "response_type", "code" }, { "scope", "openid profile" }, { "prompt", "login" }, // For a proper JWT structure, we need to include the following four claims in our JWTs { "iss", Properties.Settings.Default.ClientID }, { "aud", wellknown["issuer"]?.ToString() }, { "iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds() }, { "exp", DateTimeOffset.UtcNow.AddHours(1).ToUnixTimeSeconds() }, }; // Here, we use https://github.com/dvsekhvalnov/jose-jwt for the key operations // Let's first get our private sigKey from Settings Jose.Jwk sigKey = Jose.Jwk.FromJson( Properties.Settings.Default.JwkSigPrivateKey, Jose.JWT.DefaultSettings.JsonMapper ); Jose.JwsAlgorithm sigAlg = (Jose.JwsAlgorithm) Enum.Parse(typeof(Jose.JwsAlgorithm), sigKey.Alg); // We turn the dictionary into JSON, and then sign it using jose-jwt and our private key string requestObject = JsonConvert.SerializeObject(requestObjectParameters); string signedRequestObject = Jose.JWT.Encode(requestObject, sigKey, sigAlg); // And finally append client_id and our request object to the authorise URL, then redirect the end user string authorizeUrl = wellknown["authorization_endpoint"]?.ToString() + $"?client_id={Properties.Settings.Default.ClientID}&request={signedRequestObject}"; return Redirect(authorizeUrl); } ``` The above will trigger the authentication flow and expected result for the end-user when redirected. ### Encrypting the request object You are now ready to add encryption, for example to encrypt the signed request object in order to maintain the confidentiality of the message. This means that the message you send through the end-user's browser is both *signed* (so that the authorization server knows that it comes from you) and *encrypted* (so that no one except Signicat can decrypt and see the actual message that you're sending). 1. You can use the same code as you used for signing, but with an extra step to add encryption to it. This means you should use the `jwks_uri` in the `.well-known/openid-configuration` metadata to download the public set of keys (JWKs), and then choose one of the keys intended for encryption which you then use to encrypt the request object. Here is an example: ```csharp public async Task SignedAndEncrypted() { // We need some info from the .well-known/openid-configuration JObject wellknown = await GetWellknown(); // We create a dictionary to hold the parameters that we would previously // put in the query string but will now go into the request object. Dictionary requestObjectParameters = new Dictionary { { "client_id", Properties.Settings.Default.ClientID }, { "redirect_uri", RedirectUri }, { "response_type", "code" }, { "scope", "openid profile" }, { "prompt", "login" }, // For a proper JWT structure, we need to include the following four claims in our JWTs { "iss", Properties.Settings.Default.ClientID }, { "aud", wellknown["issuer"]?.ToString() }, { "iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds() }, { "exp", DateTimeOffset.UtcNow.AddHours(1).ToUnixTimeSeconds() }, }; // Below, we use https://github.com/dvsekhvalnov/jose-jwt for the key operations // Let's first get our private sigKey from Settings Jose.Jwk sigKey = Jose.Jwk.FromJson( Properties.Settings.Default.JwkSigPrivateKey, Jose.JWT.DefaultSettings.JsonMapper ); Jose.JwsAlgorithm sigAlg = (Jose.JwsAlgorithm) Enum.Parse(typeof(Jose.JwsAlgorithm), sigKey.Alg); // Now let's fetch the JWKSet and then find a public encryption key in it string jwksJson = await _client.GetStringAsync(wellknown["jwks_uri"]?.ToString()); JObject jwks = JObject.Parse(jwksJson); JToken encKeyEntry = jwks["keys"].FirstOrDefault(k => k["use"]?.ToString() == "enc"); Jose.Jwk encKey = Jose.Jwk.FromJson( encKeyEntry?.ToString(), Jose.JWT.DefaultSettings.JsonMapper ); Jose.JweAlgorithm encAlg = (Jose.JweAlgorithm) Enum.Parse(typeof(Jose.JweAlgorithm), encKey.Alg?.Replace("-", "_")); // Reflects the value set for "Content Encryption Algorithm" // on the client, in the Signicat Dashboard Jose.JweEncryption contentEncAlg = Jose.JweEncryption.A128CBC_HS256; // Using the jose-jwt library, we must also explicitly add the kid header var extraHeaders = new Dictionary() { { "kid", encKey.KeyId } }; // We turn the dictionary into JSON, and then sign it using our private key // and then encrypt it using the public enc key from the JWKSet string requestObject = JsonConvert.SerializeObject(requestObjectParameters); string signedRequestObject = Jose.JWT.Encode(requestObject, sigKey, sigAlg); string encryptedRequestObject = Jose.JWT.Encode( signedRequestObject, encKey, encAlg, contentEncAlg, extraHeaders: extraHeaders ); // And finally append client_id and our request object to the authorise URL, then redirect the end user string authorizeUrl = wellknown["authorization_endpoint"]?.ToString() + $"?client_id={Properties.Settings.Default.ClientID}&request={encryptedRequestObject}"; return Redirect(authorizeUrl); } ``` 2. To _require_ the use of request objects so that the OIDC client does not send plain authorization requests, navigate to the [OIDC client](https://dashboard.signicat.com/oidc-clients/) configuration in the Signicat Dashboard. Select your OIDC client, navigate to **Advanced** > **Security** and tick the **Requires Request Object** checkbox. Tick Requires Request Object You can now continue to ensure that the sensitive data you receive from Signicat is also encrypted (and, in the case of `userinfo`, also signed). ## Enabling encrypted ID tokens In the [Authorization code flow](/docs/eid-hub/oidc/code-examples/authorization-code-flow.mdx) guide, the `callback` method looks as follows: ```csharp public async Task Callback(string code) { string accessToken; JObject wellknown = await GetWellknown(); using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["token_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Basic", BasicAuth); httpRequest.Content = new FormUrlEncodedContent(new Dictionary { { "grant_type", "authorization_code" }, { "redirect_uri", RedirectUri }, { "code", code } }); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string responseContent = await httpResponse.Content.ReadAsStringAsync(); JObject tokenResponse = JObject.Parse(responseContent); accessToken = tokenResponse["access_token"]?.ToString(); } using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["userinfo_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string responseContent = await httpResponse.Content.ReadAsStringAsync(); return Content(responseContent, "application/json"); } } ``` There are two parts of the above `callback` method: The first takes the `code` you receive when the user returns to your application after authentication and sends it to the `token_endpoint`, and in returns gets a token response which looks like this: ```json { "id_token": "eyJhbGciOiJSUzI1NiWW...JA_xuK8tWEentQ", "access_token": "eyJhbGciOiJSUzI1NiI...kaY5bPnEcF5xJQ", "expires_in": 600, "token_type": "Bearer", "scope": "openid profile" } ``` In the `callback` method, you grab the `access_token` and use that as the bearer token to call the `userinfo_endpoint` to retrieve all the claims for the user. However, it is not required to call the `userinfo_endpoint`, since the `id_token` in the token response will return the relevant claims. Learn more about the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo). In the default setup, the `id_token` is signed (JWS) but not encrypted, so if you would base64 decode the JWS body then you would see the claims, for example: ```json { "iss": "https://docs.sandbox.signicat.com/auth/open", "nbf": 1684145090, "iat": 1684145090, "exp": 1684145690, "aud": "sandbox-happy-root-923", "amr": ["external"], "at_hash": "mE1Zbc6dFdRkGe2N0MnvmQ", "sid": "8BD83A26394C6C6EFFBD7A0112CEBC71", "sub": "JDAonVZOyWR-iQExci3RTHkWerjTK8DvhLa6yOr2CVc=", "auth_time": 1684145089, "idp": "idin-simulator", "idp_issuer": "simulator", "sandbox": true } ``` In some scenarios, you would rather have the `id_token` encrypted as well, for confidentiality reasons. To do this, you must enable the **Encrypt ID Tokens** option on the client, under **Advanced** > **Security**. 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Edit** next to the client you wish to use. 3. In the client menu, navigate to **Advanced** > **Security** and tick **Encrypt ID Tokens**. 4. Select **Update** to save the changes. By doing so, the `id_tokens` that you receive are both signed and encrypted (JWE). To use this feature, you must first upload the public encryption key to the client (**Advanced** > **Public keys**). You may also use the **Add public key** feature instead, in which case you let Signicat generate a private-public key pair for you, for convenience: Add public encryption key Signicat will not store the private key, so when the key has been generated, you must copy it and include it in your application. Now, you should be ready to decrypt the ID tokens. To do this, modify your `callback` method accordingly: ```csharp public async Task CallbackForEncryptedIdTokens(string code) { JObject wellknown = await GetWellknown(); using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["token_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Basic", BasicAuth); httpRequest.Content = new FormUrlEncodedContent(new Dictionary { { "grant_type", "authorization_code" }, { "redirect_uri", RedirectUriForEncryptedIdTokens }, { "code", code } }); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string responseContent = await httpResponse.Content.ReadAsStringAsync(); JObject tokenResponse = JObject.Parse(responseContent); // The above is the same as previously, // and the relevant changes are the ones below: string encryptedIdToken = tokenResponse["id_token"]?.ToString(); Jose.Jwk encKey = Jose.Jwk.FromJson( Properties.Settings.Default.JwkEncPrivateKey, Jose.JWT.DefaultSettings.JsonMapper ); // The header of the incoming encrypted id token will // tell me both the alg and the enc used. Additionally, // the enc is configured in the Signicat Dashboard // where it is called "Content encryption algorithm". string decryptedIdToken = Jose.JWT.Decode( encryptedIdToken, encKey, Jose.JweAlgorithm.RSA_OAEP, Jose.JweEncryption.A128CBC_HS256 ); return Content(decryptedIdToken, "text/plain"); } } ``` In this particular case and with the described setup example, there is only one encryption key associated with the client, so you can assume that the ID token will always be encrypted using that key. If there are multiple encryption keys on a client, then it would be necessary to check the `kid` in the header of the incoming encrypted ID token and then select the corresponding private key for decryption. ### Verifying the ID token signature Regardless of using unencrypted or encrypted ID tokens, you must always be careful to validate the signature of the ID token to verify its authenticity. For that purpose, we introduce a helper method: ```csharp public async Task VerifySignature(string jws) { JObject wellknown = await GetWellknown(); // First we fetch the key id, kid, from the header IDictionary headers = Jose.JWT.Headers( jws, Jose.JWT.DefaultSettings ); string kid = headers.First(h => h.Key == "kid").Value.ToString(); // Now let's fetch the key from the JWKSet published by the authorization server string jwksJson = await _client.GetStringAsync(wellknown["jwks_uri"]?.ToString()); JObject jwks = JObject.Parse(jwksJson); JToken sigKeyEntry = jwks["keys"].FirstOrDefault(k => k["kid"]?.ToString() == kid); Jose.Jwk sigKey = Jose.Jwk.FromJson( sigKeyEntry?.ToString(), Jose.JWT.DefaultSettings.JsonMapper ); // And finally we verify the signature return Jose.JWT.Decode( jws, sigKey, Jose.JwsAlgorithm.RS256, Jose.JWT.DefaultSettings); } ``` Once you have decrypted the ID token (see the [previous section](#enabling-encrypted-id-tokens)), you obtain a signed JWT (JWS). The header of the JWS tells you which key was used to sign it; you fetch that key from the `jwks_uri` endpoint and feed it into the `Jose.JWT.Decode` method, which verifies the signature and then returns the plain claims. You modify your `callback` method to include this verification at the end: ```csharp string verifiedIdToken = await VerifySignature(decryptedIdToken); ``` And this yields the following result: ```json { "nbf": 1684156135, "exp": 1684156735, "iss": "https://docs.sandbox.signicat.com/auth/open", "aud": "sandbox-happy-root-923", "at_hash": "A-5ERuKcv5zh1VHPVCu54g", "sid": "8BD83A26394C6C6EFFBD7A0112CEBC71", "sub": "JDAonVZOyWR-iQExci3RTHkWerjTK8DvhLa6yOr2CVc=", "auth_time": 1684156135, "idp": "idin-simulator", "idp_issuer": "simulator", "sandbox": true, "amr": ["external"] } ``` ## Signed and encrypted userInfo responses This section completes the equivalent exercise for the userInfo as well (even though we stated above that it is usually not required to interact with the `user_info` endpoint since the ID token will be sufficient). 1. Open your client in the Signicat Dashboard, select **Advanced** > **Security** and then choose to have your userInfo signed and encrypted: UserInfo 2. Since you will be decrypting JWTs again as described in the [ID token](#verifying-the-id-token-signature) section, you should refactor the decryption to a separate method: ```csharp public string Decrypt(string jwt) { Jose.Jwk encKey = Jose.Jwk.FromJson( Properties.Settings.Default.JwkEncPrivateKey, Jose.JWT.DefaultSettings.JsonMapper ); return Jose.JWT.Decode( jwt, encKey, Jose.JweAlgorithm.RSA_OAEP, Jose.JweEncryption.A128CBC_HS256 ); } ``` 3. Go back to your callback method again to modify your previous handling of the userInfo response to the following: ```csharp using (var httpRequest = new HttpRequestMessage(HttpMethod.Post, wellknown["userinfo_endpoint"]?.ToString())) { httpRequest.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); HttpResponseMessage httpResponse = await _client.SendAsync(httpRequest); string encryptedUserInfo = await httpResponse.Content.ReadAsStringAsync(); string decryptedUserInfo = Decrypt(encryptedUserInfo); string verifiedUserInfo = await VerifySignature(decryptedUserInfo); return Content(verifiedUserInfo, "application/json"); } ``` Executing this final code, you should end up with the following set of decrypted and authentic (in terms of the verified signature) claims: ```json { "idp_id": "FANTASYBANK1234567890", "gender": "0", "sub": "JDAonVZOyWR-iQExci3RTHkWerjTK8DvhLa6yOr2CVc=", "idp_issuer": "simulator", "iss": "https://docs.sandbox.signicat.com/auth/open", "aud": "sandbox-happy-root-923" } ``` To summarise, your code and integration should now use signed and encrypted request objects, ID tokens and userInfo responses, verifying both integrity and authenticity of all exchanged messages. --- ## FAQs about OIDC Get answers to frequently asked questions about your OIDC implementation with Signicat. ### How do I add more redirect URIs? Go to your [**OIDC client**](https://dashboard.signicat.com/oidc-clients) in the Dashboard and select **Edit**. In the **URIs** tab, you can change, remove or add multiple URIs. ### How do I change the allowed scopes? Go to your [**OIDC client**](https://dashboard.signicat.com/oidc-clients) in the Dashboard and select **Edit**. In the **Access** tab, you can manage the allowed scopes. ### I lost or want to change a client secret - what do I do now? If you lose a client secret, you must generate a new one. The value of a client secret cannot be recovered because Signicat only stores the hash code of the secret, for security reasons. Client secrets are automatically generated and their value cannot be customised. This is a security feature. ### Why can't I see all the claims in the ID token? When you create a client, it is configured to return only the claims defined in the OIDC standard (standard scopes). To change this, go to your [**OIDC client**](https://dashboard.signicat.com/oidc-clients) in the Dashboard and select **Edit**. In the **Advanced** > **Security** tab, you can choose the level of **ID Token User data**. Other reasons why you don't receive all the claims data could be: - The end-user data is not present in the IdP database. - The IdP did not return the data requested. - The end-user did not consent to sharing the data. ### How can I get end-users to re-authenticate every time? (Disable SSO) To force the end-user to re-authenticate every time, pass the query parameter `prompt=login` in your [authorization request](/docs/eid-hub/oidc/oidc-implementation.mdx#authorization). :::note Maximum Authentication Age (`max_age=0`) When forcing re-authentication, avoid using `max_age=0` as an alternative to `prompt=login`. ::: ### How do I auto-select a specific eID/IdP? (Skip eID selection screen) To control which eIDs to display to your end-users, you can use the `acr_values` query parameter with the format `acr_values=idp:idp_name`. Learn more about this feature in the [IdP scoping](/docs/eid-hub/oidc/oidc-implementation.mdx#idp-scoping) documentation. ### How do I show only certain IdPs? Go to your [**OIDC client**](https://dashboard.signicat.com/oidc-clients) in the Dashboard and select **Edit**. In the **Access** tab, you can configure the **Identity provider restrictions**. Learn more about this feature in the [IdP scoping](/docs/eid-hub/oidc/oidc-implementation.mdx#idp-scoping) documentation. ### How do I enable PKCE? Go to your [**OIDC client**](https://dashboard.signicat.com/oidc-clients) in the Dashboard and select **Edit**. In the **Advanced** > **Security** tab, tick the **Require PKCE** box. We strongly recommend using PKCE. See the section on [Advanced security considerations](/docs/eid-hub/oidc/advanced-security/proof-key-for-code-exchange-pkce.mdx) for further information. ### How do I enable additional encryption and/or signing of messages? There are two supported options: 1. Signicat sends you encrypted/signed responses. Learn more [here](/docs/eid-hub/oidc/advanced-security/receive-encrypted-signed-responses.mdx). 2. You send encrypted/signed requests to Signicat. Learn more [here](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests.mdx). ### How do I change the language in the authentication flow? Localisation best practices suggest giving users control over their language preferences. Browsers support user language customisation - sent via the “Accept-Language” request header. Signicat uses the preferred languages, if available. The fallback language is set to **English**, by default. Note that IdPs might support many languages: English and the IdP native language. In cases where you want to override end-user language preferences, use the authorization query string parameter `ui_locales`, according to OIDC specifications. ### How do I send prefilled information? See the [`login_hint` documentation](/docs/eid-hub/oidc/oidc-implementation.mdx#login_hint). ### Can I send extra information in a request, and get it in a response? The OIDC/OAuth specification does not have any recommended way. The OAuth 2.0 specification states that redirect URIs must be absolute URIs. Ideally, your system should be agnostic. It should handle authentication requests and complete the process based on the end-user data obtained from the ID token. If this is not possible you can consider encoding data in the “state” parameter. This is not an official method but a widespread workaround. The data can be base64 encoded, with a hash or a reference, or encoded as a compact JWT. --- ## OpenID Connect OpenID Connect (OIDC) is an authentication protocol based on the OAuth 2.0 protocol. OAuth 2.0 is a framework designed to support the development of authentication and authorisation protocols. It provides a variety of standardised message flows based on JSON and HTTP, used by OIDC to provide identity services. OIDC aims to support end-user authentication and identity information on top of the OAuth 2.0 protocol. ## Signicat OIDC server Signicat offers the Signicat OIDC server as part of our Digital Trust Platform. The principles of the Signicat OIDC server is that it should be compliant with standards while supporting all the features of our solutions. :::info Signicat is a certified OpenID provider - Signicat is certified by the OpenID Foundation as a Basic and Hybrid OpenID Provider of the OpenID ConnectTM protocol. To explore our certification details, visit OpenID's list of [Certified OpenID Providers](https://openid.net/certification/#OPs). ::: The OpenID certification is an assurance that the Signicat OpenID server is compliant with OIDC standards and guarantees a more secure implementation for you. ## Get started * [**Set up an OIDC client**](/docs/eid-hub/oidc/oidc-client): Set up an OIDC client before you start the integration * [**OIDC implementation**](/docs/eid-hub/oidc/oidc-implementation): Learn about OIDC flows, endpoints, claims, key rotation and more * [**Test connections**](/docs/eid-hub/oidc/test-connections): Try it out before you start integrating * [**Code examples**](/docs/eid-hub/oidc/code-examples): Dive deep into code examples ## Advanced topics * [**Native Mobile Apps**](/docs/eid-hub/oidc/native-mobile-apps): Discover best practices for Native Mobile Applications * [**Advanced security considerations**](/docs/eid-hub/oidc/advanced-security): Learn about advanced security measures like PKCE and encryption * [**CIBA (OIDC extension)**](/docs/eid-hub/oidc/ciba): Learn about CIBA and how to set it up ## Migration guides * [**Migrating from Enterprise**](/docs/eid-hub/migration-guides/enterprise/migration-guide-oidc): Understand the differences before you migrate * [**Migrating from Broker**](/docs/eid-hub/migration-guides/signicat-identity-broker/migration-guide-oidc/): Understand the differences before you migrate ## Troubleshooting * [**Frequently asked questions**](/docs/eid-hub/oidc/faqs): Find answers to your questions about OIDC with Signicat * [**Error codes**](/docs/eid-hub/oidc/oidc-error-codes): View the error codes for OIDC connections --- ## Native mobile apps When integrating OIDC flows in the development of native mobile apps, you should adhere to best practices to ensure the security and privacy of user data. One important aspect is how your application performs OIDC authorization requests to offer your users authentication through identity providers. This guide outlines the recommended approach to designing your native mobile apps and discusses topics such as preferring external user-agents (such as the browser), configuring redirect URIs and opting for PKCE over client secrets. :::warning App switching on mobiles with MitID This page does not apply if you set up an integration with MitID. If you want to perform a MitID authentication from your native mobile app, please see the MitID Integration guide > [App switching on mobiles](/identity-methods/mitid/integration-guide/app-switching/) instead. ::: :::tip References The content of this guide is based on [RFC 8252: OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252), which we recommend reading to dive deeper into best practices for native apps in the context of OIDC. Other suggestions on this page are the result of Signicat's many years of industry experience and discussions with experts in the OIDC field. ::: :::note Glossary In this guide, we use the term “native app” to refer to an application intended to run natively on a mobile operating system (OS), such as Apple iOS or Google Android. Web apps, including progressive web apps and single-page applications, that run natively in browsers are not covered here. ::: ## Challenges with native apps Building an integration for native apps presents the following challenges: - Secrets stored in a native app are not secure. - Fragmentation of mobile operating systems: - Devices can run the latest or any number of older versions of Android or iOS. - OS versions can have breaking changes between versions. - On Android, there are often vendor-specific OS versions. - Fragmentation of web browsers: - On Android, there can be OS-branded browsers, the most common is the “Samsung Browser”. - Safari is the standard browser for iOS but many users install other browsers, causing the interaction between Safari and the other browsers to be unpredictable. - Embedded browsers (such as when implemented in web views) are considered unsafe. Learn more in the [System browsers VS web views](#system-browsers-vs-web-views) section. - Redirecting users between browser-to-app or app-to-app is challenging on both Android and iOS. Despite several attempts by mobile developers to fix this, the issue has not been solved yet. To mitigate these challenges with native apps consider the points in the section below. ## Key points for a secure integration To increase the security of your native app, your application: - **MUST NOT use client secrets**: Don't use client secrets on native apps because they are not considered safe. You should view your OIDC client as a “public client”. - **MUST use PKCE**: Public clients are susceptible to the authorization code interception attack. PKCE (Proof Key for Code Exchange) mitigates this threat. - **Redirect URIs MUST be HTTPS**: Signicat disallows custom URI schemes and loopback URIs. We strongly encourage using URIs that are domain-verified with the OS vendor. Learn more in the [Redirect URIs](#redirect-uris) section. - **MUST NOT use web views**: When launching authentication views to the end-user, design your application to open views in the system browser and not as a web view. Learn more in the [System browsers VS web views](#system-browsers-vs-web-views) section. ### Redirect URIs Redirects using custom URI schemes (for example `my-unsafe-app://redirect`) are not considered safe because other apps could hijack your custom URI scheme. The safest option is to use ”universal links” or ”app links” that have verified domains with Apple or Google respectively. This solution reduces the risk that other apps or malicious actors on the end-user device hijack your redirect URIs. For further information on this topic, consult vendor-specific documentation. ### System browsers VS web views Web views (which implement embedded user-agents) are problematic for authentication flows for several reasons: - They can appear less safe to end-users as there is no information on the URL of the webpage or the certificate. - The cookies that exist in system browsers are not available in web views. - The host app can copy user credentials and cookies. - If the OS or end-user triggers a switch to the system browser during the process, the authentication flow might fail in unpredictable ways. For these reasons, web views are not supported. By avoiding embedded user agents such as web views, you protect user data from potential vulnerabilities. Conversely, using only external user-agents (with the system browser) for OAuth 2.0 authorization requests in native apps is the best current practice, according to [RFC 8252: OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252). This process, also known as "AppAuth pattern", ensures a secure and trusted environment for users while maintaining the integrity of the app's authentication and authorization processes. Note that if the end-user has multiple browsers installed on their device, "app switching" between additional browsers and the default browser (Chrome on Androids, Safari on iOS) could occur. This may lead to issues similar to the ones mentioned above. Although there is no definitive solution for this issue, Signicat works to mitigate it where possible. When implementing your solutions, you should be aware of the potential impact. ## Configuring a client in the Signicat Dashboard When you create your OIDC application with Signicat, you can customise your OIDC client to adhere to best practices. Signicat offers an OIDC client template with the correct configuration for native apps. ### Create a new OIDC client To create a new OIDC for native apps with this template: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) and select **Add client**. 2. In **Primary Grant Type**, select which grant type (flow) you want to use with this client. We strongly recommend **AuthorizationCode**. 3. In **Create client from template**, choose “Native/Mobile Application”. Use this template when creating an OIDC client for native apps. 4. Enter the name for the client. 5. Add your Redirect URIs, which should be domain-verified as explained in the [Redirect URIs](#redirect-uris) section above. 6. Click **Create** to create a client for native apps. When creating the client, you can skip secret creation as you should use PKCE instead of a client secret. For further information about clients, see [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). ### Edit existing OIDC clients To edit an existing OIDC client with the correct configuration for native apps: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select the client you wish to use. 3. In the client menu, click **Advanced > Security**, then untick **Requires Secret** and tick **Requires PKCE**. 4. Add your Redirect URIs, which should be domain-verified, as explained in the [Redirect URIs](#redirect-uris) section above. Now, you can use the client in your native mobile app to authenticate your end-users. ## Alternative approach: Authentication REST API Many of our customers prefer to integrate their native apps with the [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) protocol instead of OIDC. The main reason is that with the Authentication REST API most of the login complexity is managed in the backend of your application. However, this means greater responsibility for your developers to ensure that the binding between a native app and your backend system is properly secured. Some customers also prefer the general advantages of integrating with a standard REST API, instead of having to deal with open standards, such as OAuth and OIDC. ## Next steps Dive deeper into OIDC and improve your application with advanced security features: * [**Advanced OIDC implementation**](/docs/eid-hub/oidc/oidc-implementation): Learn about available flows, endpoints, claims, key rotation, security, error codes etc. * [**Advanced security considerations**](/docs/eid-hub/oidc/advanced-security): Learn about advanced security measures like PKCE and encryption Discover the features of the Signicat Authentication REST API: * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Authenticate your end-user easily and securely with the Signicat Authentication REST API. --- ## Set up an OIDC client To start authenticating users with OpenID Connect, you first need to register an **OIDC client** in the Signicat Dashboard. An OIDC client provides you with a **Client ID** that you use in your authentication requests. Depending on the authentication grant type (flow), you may need to add a **client secret**. On this page, you can learn about how to create and configure an OIDC client in the Signicat Dashboard and prepare yourself to connect to eIDs in the Signicat eID and Wallet Hub. :::tip Video instructions You can find a video that shows you how to set up an OIDC client in the [Tutorial video](#tutorial-video) section. ::: ## Add a new OIDC client To add a new OIDC client in the Signicat Dashboard, do the following: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Add client**. 3. Configure the following properties: - **Primary grant type**: Choose the grant type you want to implement. We strongly recommend **AuthorizationCode**. For more information about grant types, refer to the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#Authentication) and the [OAuth 2.0 specification](https://oauth.net/2/grant-types/). - **Create client from template**: Optional. Choose a template to suit your use case. Doing this prefills your client configuration automatically. - **Client name**: Enter a name for the client. - **Redirect URI**: Enter the URL where you want to redirect your end-user after they authenticate with an eID. You can add several redirect URIs after you create the client. - **Scope**: Select the scopes for the user attributes you want to retrieve with this client. `openid` is mandatory. `profile` and `nin` are necessary in most cases. You can see the definition of `profile` and other predefined scopes in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). You find scope definitions in the specific [eIDs](/docs/eid-hub/e-ids/) documentation. 4. Select **Create** to create the new client. :::info Success! You have now created a new OIDC client. You can view and edit your client in the **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) page. ::: Before you can start using the client in your application, you might need to add extra configurations. The next sections explain how to extend your client configuration for the different types of authentication flow. ## How to create a client secret To add a secret to your OIDC client, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Edit** next to your client name. 3. In the client menu, go to the **Secrets** tab, then select **Add secret**. 4. Enter a name for your client secret, then select **Generate secret**. 5. Copy your new client secret and store it safely. :::warning Important Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one. ::: ## OIDC configuration options We support additional configuration options for OIDC clients, such as: - **PKCE (Proof Key for Code Exchange)**: We strongly recommend using PKCE. To enable PKCE in your OIDC client, navigate to the **Advanced** > **Security** tab and tick **Require PKCE**. - **Encryption**: If you require encryption, you can upload a public key by navigating to the **Advanced** > **Public keys** tab and clicking **+ Add public key**. - **Redirect URIs**: To configure additional redirect URIs, navigate to the **URIs** tab, then click **Add new**. - **Scopes**: To add or remove scopes from your client, navigate to the **Access** tab and enter the scope code in the **Allowed scopes** field. ## Try it out You can run a test authentication with your OIDC application by using [**OAuth Tools**](https://oauth.tools/), a public web application to test OIDC flows. To learn how to run a test authentication with an eID, visit the [Test connections](/docs/eid-hub/oidc/test-connections.mdx) guide. ## Tutorial video This video shows you how to set up an OpenID Connect (OIDC) Client for our solutions in the Signicat Dashboard. --- ## OIDC error codes When you make a call to the Signicat OIDC server and an error occurs, you will receive a response with an error code. The information on this page provides more context to help you understand the cause of common errors. If you encounter an error and require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/support-tickets/tickets/new) in the Signicat Dashboard. :::note Troubleshoot the error log in the Dashboard You can find the complete log of any error in the [Signicat Dashboard > eID and Wallet Hub > Audit Log](https://dashboard.signicat.com/audit). ::: ## Handling OIDC errors We follow the OIDC and OAuth standards as closely as possible, including how we handle error messages. **Authorization errors** Errors from the `/authorization` endpoint are typically returned as URL parameters to the redirect URI. These parameters are: :::CustomTable | Parameter | Definition | |-----------|------------| | `error` | The error code. | | `error_description` | A brief description of the error. | ::: If an error cannot be passed in the redirect URI, we display an [error page](https://api.signicat.com/auth/open/connect/authorize?response_type=code&scope=openid&client_id=INVALID_CLIENT) instead. These errors usually result from an incorrect implementation or invalid configuration and are typically not caused by an end-user interacting with a service. **Token and userInfo errors** Errors from the `token` and `UserInfo` endpoints follow the OpenID Connect and OAuth protocol specifications: 1. [Token error response](https://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse) 2. [UserInfo error](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) **Standard errors** Additionally, standard HTTP status error codes may be returned, including: :::CustomTable | Status | Error type | Description | |--------|------------|---------| | 5xx | Server Errors | Internal failures within a service. | | 404 | Not Found | The requested URL is incorrect. | ::: For a list of common OIDC error codes, see the table below. :::tip Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: ## Common OIDC error codes --- ## OIDC implementation OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It enables service providers to verify the identity of an end-user based on the authentication performed by an authorisation server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner. ## Flows OpenID Connect (OIDC) lets developers authenticate users across websites and apps without having to own and manage password files. Signicat's _authorisation server_ supports the following _grant types_ (often also called _flows_ - or _protocol flows_) defined on OpenID Connect and OAuth 2.0 specifications: - Authorisation code - Hybrid - Client-Initiated Backchannel Authentication (CIBA) Grant types specify how a client can interact with the token service. To learn more about the different flows and their differences, refer to the [OIDC documentation](https://openid.net/specs/openid-connect-core-1_0.html#Authentication). The **Authorization code flow** and the **Hybrid flow** are described in this document. To learn more about CIBA, and how it compares to other flows, refer to the [CIBA (OIDC extension)](/docs/eid-hub/oidc/ciba.mdx) documentation. ### Authorization code flow The authorization code flow provides you with an authorization code. You can exchange the authorization code for an ID token, an access token and a refresh token (optional) at the `token` endpoint of our OIDC server. This process provides the benefit of not exposing any tokens to the user agent (and possibly other malicious applications with access to the user agent). For the authentication server to trust the client before exchanging any authentication data regarding the end-user, the server can authenticate the client. The authentication code flow is therefore suitable for clients that can securely maintain a client secret between themselves and the OIDC authentication server. The authorization code flow steps for performing authentication to log in the end-user (or to determine that the end-user is already logged in) are as follows: 1. The user agent requests to be authenticated. 2. The client prepares an authentication request and sends the request to the OIDC server. 3. The authorisation server authenticates the end-user. 4. The authorisation grant code is requested. 5. The OIDC server obtains end-user consent (optional). 1. If consent is asked for but denied, the end-user will not be authorised and will not be able to access their resources. The login will be stopped. The process will end at this step. 2. If consent is asked for and given, the end-user will be authorised. The process continues with step 6. 6. The OIDC server sends the end-user back to the client with an authorization code. 7. The client requests a response using the authorization code at the `token` endpoint of our OIDC server. 8. The client receives a response that contains an ID token, an access token and a refresh token (optional) in the response body (among other parameters). 9. The client validates the ID token, retrieves the end-user's subject identifier and requests resources. {/*diagram erased, need an updated one*/} ### Hybrid flow The hybrid flow combines the implicit flow with the authorization code flow. With the hybrid flow, some tokens are returned from the `/authorize` endpoint and others are returned from the `/token` endpoint. Here's a brief summary of how the hybrid flow works: 1. The user agent requests resources. 2. The client prepares an authentication request and sends it to the OIDC server. 3. The authorisation server authenticates the end-user. 4. The authorisation grant code is requested. 5. The OIDC server obtains end-user consent. 6. The authorisation server sends the end-user back to the client with an authorization code and, depending on the response type, one or more additional parameters. 7. The client requests a response using the authorization code at the `token` endpoint of our OIDC server. 8. The client receives a response that contains an ID token and an access token in the response body (among other parameters). 9. The client validates the ID token and retrieves the end-user's subject identifier. ## Claims At the heart of OIDC are **claims** - an attempt to standardise all the different units of information about an end-user. A claim may, for instance, be an end-user's surname or email address. Claims are similar to the concept of assertions in SAML, though claims in OIDC are represented (as everything else in OAuth 2.0/OIDC) as JSON key-value pairs. **Where to get claims?** The OIDC specification details two sources of claims: - The **ID token** - The **`UserInfo` endpoint** The **ID token** is a signed JSON object (a JSON web token, or JWT) containing the authentication result. You can learn more about the ID token in the [OIDC documentation](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). Some claims in the ID token are optional and can be left out depending on how much information you want it to contain. The **`UserInfo` endpoint** is a separate endpoint that accepts access tokens and returns information about the end-user. An access token represents an authorisation from the end-user to the client to perform actions on the end-user's behalf. Therefore, only information that the end-user has authorised should be returned. The `UserInfo` claims that can be returned are largely standardised but can be infinitely extended. :::tip Note We strongly recommend that you use only the ID token for obtaining claims. Using `UserInfo` usually adds complexity for very little benefit. ::: ## Signing keys The signing key is a JSON web key (JWK) which contains the public part of an asymmetrical key pair. In general terms, a JWK is a JSON object that represents a cryptographic key. Signing keys ("use": "sig") are published through JSON web key set (JWKS), a well-known URL available at your Signicat domain. Signicat signs each token with the private key on the authorisation server side. To verify that a JWT token is valid and originated from the Signicat authorisation server, your application needs to verify the token's signature using the public key published in the JWKS. Signature validation ensures that the token was issued by Signicat and that no one has tampered with the token. ### JSON web key set (JWKS) A JSON web key set (JWKS) contains a set of keys containing the public keys that your application can use to validate Signicat-issued tokens (JWT), like access and ID tokens. Note that while the JWKS may contain multiple keys, your application needs to use only one JWK to validate the token's signature. The JWKS is available at a public endpoint in your Signicat domain. To find your JWKS endpoint: 1. Go to `https:///auth/open/.well-known/openid-configuration`. 2. Locate the endpoint specified in the `jwks_uri` field. 3. Go to the JWKS (`jwks_uri`) endpoint. The JWKS endpoint contains a JSON with a list of keys for both: - Production signing keys - Sandbox signing keys :::tip Sandbox signing keys Sandbox keys are prefixed with “sandbox-”. For example, `"kid": "sandbox-signing-key-one"`. ::: Learn more about JWK parameters in the [RFC 7517 Internet Standards](https://datatracker.ietf.org/doc/html/rfc7517#section-4). ### Key rotation Key rotation is a process to retire and replace cryptographic keys. This is an industry standard and follows cryptographic best practices. The JSON web key set (JWKS) endpoint returns several unordered JSON web keys (JWKs) at any given time. The keys in the key set are subject to change because of key rotation. :::note Key rotation schedule We rotate keys once a month, but this can change without notice. New keys are normally generated a few days before rotation so that you can update you caching mechanisms before the rotation occurs. ::: When validating a token consider the following: - If token signature validation fails, fetching the current key set returns a set where one of the keys is valid. - New keys for token signing are published to the JWKS endpoint before we retire the key in use for signing. This gives you enough time to fetch the new key set and update your cache. :::tip When to update your cache? We recommend you refresh your replica, or cache, of signing keys regularly. Note that we rotate keys frequently. For instance, you could follow these guidelines: - Refresh your cache when a `kid` (key identifier) is present in the JWKS, but not in your cache. - Remove a key when the `kid` is present on your side, but not in the JWKS. ::: ## Default signing and encryption - Encryption algorithm: AES-128 - Supported key length: 2048-bit (4069-bit also supported) - Signature hash: SHA-256 :::CustomTable{columnWidths="33% 33% 33%"} | **What?** | **Signing** | **Encryption** | | :------------------ | :----------------------- | :----------------------- | | ID token | Always | Optional, off by default | | Access token | Always | Never | | `UserInfo` response | Optional, off by default | Optional, off by default | ::: :::warning Note Elliptic curve cryptography (ECC) key pairs are not supported at the moment. If your implementation requires this feature, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Endpoints The following endpoint URLs are available for communicating with the OpenID Connect provider through Signicat. ### Authorization The Authorization endpoint is where you send the end-user to perform an authentication. You can find your OIDC authorization endpoint at `https:///auth/open/connect/authorize`. For example, if your domain is `https://verybigcorp.signicat.com`, your discovery URL is `https://verybigcorp.signicat.com/auth/open/connect/authorize`. **Example authentication request** ```curl https:///auth/open/connect/authorize ?client_id= &redirect_uri= &response_type= &scope=openid%20profile &code_challenge=ABC123 &code_challenge_method=S256 &response_mode=query &state=12345 &nonce=678910 ``` You can find the full list of available request parameters in the ['Authentication Request' section](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of the OIDC documentation. #### acr_values You can use `acr_values` to adjust how the authentication flow behaves. There are generic parameters (listed below) that apply to all identity providers (IdPs), as well as IdP-specific parameters. The format of the parameter is a space-separated list of key-value pairs: `acr_values=key1:value1 key2:value2`. To specify multiple values for the same key, use the comma-separated format: `acr_values=key1:value1a,value1b`. **Example:** `acr_values=idp:idp_name,other_idp_name loa:high` **Result:** IdP will be pre-selected for the end-user; Level of Assurance is set to *high*. **Available parameters:** :::CustomTable{columnWidths="25% 75%"} | **Name** | **Description** | |:---------|:-----------------------------------------------------------------------| | `idp` | Defines the IdPs to use. Learn more in [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx?protocol=oidc). This works in conjunction with `login_hint`. | | `loa` | Specifies the eIDAS [Level of Assurance (LoA)](/docs/dashboard/glossary.mdx#level-of-assurance-loa). Allowed values: `low`, `substantial` or `high`. | | `theme` | Specifies the theme to use. | ::: ##### Set acr_values at the client level Typically, you define `acr_values` as a query parameter in your authorization request. However, you can also configure ACR values at the client level, thus applying specific values to all the requests by default without the need to define `acr_values` explicitly for each request. You can configure default `acr_values` in your OIDC client in the Signicat Dashboard. To do this: 1. Navigate to **Products** > **eID and Wallet Hub** > [**OIDC client**](https://dashboard.signicat.com/oidc-clients). 2. Choose your OIDC client and select **Edit**. 3. Navigate to the **Access** tab, then edit the **ACR values** field with the values you want to use by default in all requests. 4. Optional. Tick the **Force use ACR values** box to prevent that ACR values are overridden or changed when defined as query parameters in a request. Any ACR values you configure in the Dashboard apply now to all authentication flows by default. Note that passing `acr_values` as a query parameter in the request overrides the default values you configure in the client in the Dashboard, unless you force the use of ACR values. #### login_hint You can use this `login_hint` to prefill end-user information to send to the IdP, such as the national identification number of the end-user. The format is a space-separated list of key-value pairs: `login_hint=key1:value1 key2:value2`. **The following pre-filling options are available:** :::CustomTable{columnWidths="50% 50%"} | **Name** | **Description** | | :------------------ | :------------------------------ | | `nin` | National identification number. | | `mobile` | Mobile phone number. | | `dateOfBirth` | Date of birth (YYYY-MM-DD). | | `email` | Email address. | | `username` | Username or User ID. | | `deviceID` | Mobile Device ID. | | `firstName` | First name. | | `lastName` | Last name. | | `bankAccountNumber` | Bank account number. | | `organisation` | Organisation name. | ::: You can find specific configuration examples for the following eIDs here: - [Swedish BankID](/identity-methods/sbid/integration-guide/) - [Norwegian BankID](/identity-methods/nbid/integration-guide/) - [SMS OTP](/identity-methods/sms-otp/setup/oidc.mdx) - [MobileID](/identity-methods/mobileid/integration-guides/oidc/ciba-flow/implementation/#login-hint) :::warning `login_hint` and `acr_values` field format Note that query parameters must be URL encoded (percent encoding). For example, if you want to prefill end-user mobile numbers with `login_hint`, use `login_hint=mobile:%2B447700900000` to represent the `+44 7700900000` phone number. ::: ### Token To obtain an access token, an ID token and optionally a refresh token, the client sends a token request to the `token` endpoint to obtain a token response. **Example token request** ``` curl -XPOST "https:///auth/open/connect/token" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic czZCaGRSa3FOMzpnWDFmQmFOM2JW" -d "grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://example.com" ``` **Example token response** ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5", "token_type": "Bearer", "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g", "expires_in": 3600, "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg" } ``` ### UserInfo To obtain the requested claims from the `UserInfo` endpoint, the client makes a request using an access token obtained through OpenID Connect authentication. **Example `UserInfo` request** ``` curl -XPOST "https:///auth/open/connect/userinfo" -H "Accept: application/json" -H "Authorization: Bearer fAAdL01c6QWDbPs9HrWHz5e7nRWVAnxqTTP7i88G" ``` **Example `UserInfo` response for valid access token** ```http HTTP/1.1200OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "sub": "bob" "given_name": "Bob", "name": "Bob Smith", "email": "bob@mycompany.com", "phone_number": "+1 (604) 55-555-66-777", "address": {"formatted": "123 Main St., Anytown, TX 77777"}, } ``` ## IdP scoping IdP scoping allows you to define which eIDs to make available for authentication to your users. One advantage of IdP scoping is the ability of showing only the eIDs that are relevant to the user while hiding other eIDs active in your Signicat account. To control which eID to make available to your end-users, you can use the `idp` key in the `acr_values` query parameter with the format `acr_values=idp:idp_name,other_idp_name`. For example, using `acr_values=idp:otp-sms,mitid` in your authorisation request will only display SMS OTP and MitID to the user. When specifying only one eID in your request, you automatically redirect the user to the provider authentication page, thus skipping the eIDs selection screen. To learn more about this feature and view examples for OIDC, see the [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx?protocol=oidc) documentation. #### Restrict IdPs at the OIDC client level In the Dashboard, you have the option to restrict the eIDs (active in your account) that a specific OIDC client can access. This applies when you have several OIDC clients that you use for different purposes and applications and you want to restrict the eIDs available for an OIDC client. To restrict the eIDs available for an OIDC client, do the following: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. Choose your OIDC client and select **Edit**. 3. Navigate to the **Access** tab, then enter the eIDs in the **Identity provider restrictions** field. Now, only the specified IdPs are available for authentication requests with this OIDC client. ## Error codes To learn more about error codes and their meanings, see [OIDC error codes](/docs/eid-hub/oidc/oidc-error-codes/). ## Single sign-on (SSO) [Single sign-on (SSO)](/docs/dashboard/glossary.mdx#single-sign-on-sso) allows the end-user to establish their identity once without having to re-authenticate every time they access your services. :::note Levels of SSO Signicat supports two levels of SSO, at the OIDC server and the eID and Wallet Hub level. This page describes only SSO at the OIDC server level. For more information about SSO at the eID and Wallet Hub level, see this [page](/docs/eid-hub/concepts/single-sign-on.mdx). ::: #### How it works When the end-user first logs in with SSO, the Signicat OIDC server sets, and stores, an encrypted cookie that contains information about the end-user's device. Note that the SSO scope is set at the (Signicat) account level. On subsequent logins, the Signicat OIDC server checks whether an SSO cookie is present in the user's browser. If found, the Signicat OIDC server verifies the SSO cookie validity and lifetime. If a cookie is valid and approved, the end-user is automatically redirected to your application without being asked to re-authenticate. #### SSO in the Dashboard When you create a new OIDC client, SSO is enabled by default. You can control the cookie lifetime with the **User SSO lifetime** setting. The default value is `3600` seconds (1 hour). To change the SSO session lifetime: 1. In the Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. Select **Edit** next to your client to view the client configuration. 3. Navigate to the **Advanced** > **Lifetimes** tab. 4. Edit the **User SSO lifetime** setting. 5. Select **Update** to save and apply the changes. #### Forcing re-authentication To force the end-user to re-authenticate, specify the URL parameter `prompt=login` in the authorisation request. :::note Maximum Authentication Age (`max_age=0`) When forcing re-authentication, avoid using `max_age=0` as an alternative to `prompt=login`. ::: ## Single log-out (SLO) Single log-out (SLO) is a feature that allows the end-user to sign out of multiple authenticated sessions with a single action. Signicat implements the [OpenID Connect RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) standard for end-user logout. :::warning OIDC level only At the moment, the end-user will **only** be logged out of Signicat OIDC server. Any other potential SSO session at the application, IdP or eID and Wallet Hub level will not be terminated (logout). ::: #### Example of logout To initiate logout you need to direct the end-user to the `/auth/open/connect/endsession` endpoint, as shown in the following example: ```sh https:///auth/open/connect/endsession?post_logout_redirect_uri=https://signicat.com&id_token_hint=eyJhb...QifQ...hLVNI8Q ``` You can customise the logout process by specifying the following query parameters: - `id_token_hint` (recommended). It's necessary to identify the end-user you want to log out. It should contain a valid ID Token as described in the next section. - `post_logout_redirect_uri` (optional). The URI you provide in the request must match the URI configured in the **Post Logout Redirect URI** setting of your OIDC client in the Dashboard. #### Providing an ID token If you initiate a logout request *without* providing a valid ID token the end-user will be presented with a web page that prompts them to log out, instead of automatically logging them out. The ID token provides the context necessary to log out the end-user in an automated way. Without this information, it is not possible to link the client and the end-user logout request. Therefore, without a valid ID token the end-user has to submit their consent to log out. This also means you cannot use **Post Logout Redirect URI** or **Automatic Redirect to Logout Url** functionality. #### Automatic redirect after logout After the end-user logs out, you can automatically redirect the end-user to a specific URL. You can control where to redirect the end-user with the **Post Logout Redirect URI** setting. For security reasons, you need to meet the following conditions: - Provide valid `id_token_hint` and `post_logout_redirect_uri` in the request. - Enable **Automatic Redirect to Logout Url** in the URIs configuration of your OIDC client in the Dashboard. Without these conditions the end-user gets redirected to a default confirmation logout screen. ## Finnish Trust Network (FTN) specifics ### Message Level Encryption (MLE) Due to requirements from Traficom, you must use *Full Message-Level Encryption* (MLE) for authentication with FTN. There are two different ways to achieve this. The first is required and the second is only required in certain circumstances: 1. Receiving encrypted responses from Signicat (required) 2. Sending encrypted requests to Signicat (optional) :::warning Important If you are sending **personally identifiable information (PII)** as part of your request, you must also send encrypted *requests*. ::: Both these mechanisms are described in [Advanced security considerations](/docs/eid-hub/oidc/advanced-security/). ### Authentication request signing Due to requirements from Traficom, you must sign the authentication requests when setting up FTN with the OIDC protocol. For details on how to do this, see the [Encryption/signing of the request object](/docs/eid-hub/oidc/advanced-security/send-encrypted-signed-requests/) section. :::tip PAR as an alternative The Pushed Authorization Requests (PAR) extension is accepted as an alternative to signing the authentication request. For more details about PAR, see the [Pushed Authorization Requests (PAR)](/docs/eid-hub/oidc/advanced-security/pushed-authorization-requests-par/) section. ::: ## External references ### OpenID Connect - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) - [OpenID Connect Session Management 1.0 _draft 28_](https://openid.net/specs/openid-connect-session-1_0.html) - [OpenID Connect Front-Channel Logout 1.0 _draft 02_](https://openid.net/specs/openid-connect-frontchannel-1_0.html) - [OpenID Connect Back-Channel Logout 1.0 _draft 04_](https://openid.net/specs/openid-connect-backchannel-1_0.html) ### OAuth 2.0 - [OAuth 2.0 - RFC 6749](https://tools.ietf.org/html/rfc6749) - [OAuth 2.0 Bearer Token Usage - RFC 6750](https://tools.ietf.org/html/rfc6750) - [OAuth 2.0 Multiple Response Types](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html) - [OAuth 2.0 Form Post Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html) - [OAuth 2.0 Token Revocation - RFC 7009](https://tools.ietf.org/html/rfc7009) - [OAuth 2.0 Token Introspection - RFC 7662](https://tools.ietf.org/html/rfc7662) - [Proof Key for Code Exchange - RFC 7636](https://tools.ietf.org/html/rfc7636) - [JSON Web Tokens for Client Authentication - RFC 7523](https://tools.ietf.org/html/rfc7523) - [OAuth 2.0 Device Authorization Grant - RFC 8628](https://tools.ietf.org/html/rfc8628) --- ## Test connections(Oidc) This page describes how you can test an authentication with OpenID Connect using [**OAuth Tools**](https://oauth.tools/), a public web application to test and experiment with OIDC flows. For testing purposes, this guide shows steps to complete an Authorization Code Flow using Norwegian BankID. However, you may easily adapt the instructions to test all the other eIDs available in the Signicat eID and Wallet Hub. Additionally, you can find eID-specific test guides in the respect [eID documentation](/identity-methods/). :::tip Sandbox account We recommend you run test authentications by using a sandbox account. ::: ## Initial preparations Before you can run a test authentication, make sure to complete the following configuration in the Signicat Dashboard. :::tip New customers If you are new to Signicat, we recommend you first read the [Get started with Signicat](/docs/) page. ::: ### 1. Add an eID To add an eID to your Signicat account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ### 2. Create an OIDC client You need to create an OIDC client with the relevant scopes. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. Click **Create client**. 3. In the **Primary Grant Type** field, select **AuthorizationCode** from the dropdown menu. 4. In the **Client name** field, give your client a name. 5. In the **Redirect URI** field, set `https://oauth.tools/callback/code`. 6. In the **Scope field**, set `profile` and `nin`, in addition to `openid`. Optionally, you may add more attributes depending on what user data the eID supports. ### 3. Add a secret To add a secret to your OIDC client, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Edit** next to your client name. 3. In the client menu, go to the **Secrets** tab, then select **Add secret**. 4. Enter a name for your client secret, then select **Generate secret**. ## Test connection You can test an authentication by importing your OIDC client inside the OAuth Tools environment. ### 1. Import your client in OAuth Tools 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. Click the **Edit** button beside your new OIDC client. 3. Select the **Overview** tab, then click **Try out this client on oauth.tools!**. ### 2. Configure Signicat Playground settings :::tip First time only You only need to configure the Signicat Playground settings the first time you use OAuth Tools. After that, your configuration will be cached and available for future tests. ::: 1. In OAuth tools, expand the dropdown menu beside **Signicat Playground**, then select **Settings**. 2. On the **Endpoints** tab, verify that the contents of the **Metadata URL** in OAuth Tools matches the contents of the **Well-Known URL for client** field in the Signicat Dashboard. When you enter the URL, click **Discover** to fetch the other endpoints. :::info Where can I find this? To find the **Well-Known URL for client** field in the Signicat Dashboard: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients). 2. Click the **Edit** button beside your new OIDC client. 3. In the **Overview** tab, locate the **Well-Known URL for client** field. This is `https:///auth/open/.well-known/openid-configuration` ::: 3. On the **Clients** tab, verify that your client is visible, and that the **Code** toggle button is enabled. 4. Close the settings page. ### 3. Configure Authorization Code Flow settings 1. In the left-side menu, select **Authorization Code**. 2. In section **(1) Settings**, set the following: :::CustomTable{columnWidths="25% 75%"} | **Field name** | **Allowed values** | | :-- | :-- | | Select or enter a client ID | Use the dropdown menu to select your client. | | Select or add scope | Use the dropdown menu to set scopes. `openid` is mandatory. Set other scopes that as configured in your OIDC client, for example `profile`, `nin`. | | Select or add acr value | Optional. To route directly to Norwegian BankID and skip the eID selection screen, enter `idp:nbid`. Learn more about [ACR values](/docs/eid-hub/oidc/oidc-implementation/#acr-values). | | Select or add locale | Optional. Enter your desired language. For example, `en` or `no`. | | Prompt parameter | Optional. Use the dropdown menu to set prompt `login`. | | Login Hint | Optionally, you can set a [Login hint](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). | ::: ### 4. Start flow 1. In section **(2) Start Flow**, click the **Run** button. This will redirect you to the Norwegian BankID portal. 2. Optional. If you have activated many eIDs in the Signicat Dashboard and you have left the ACR values empty, you will be redirected to the **Select identity provider** screen. To proceed, choose **Norwegian BankID**. 3. In the Norwegian BankID portal, use the following test credentials: | National ID | OTP | Password | |:------------- |:----- |:---------- | | `01100844350` | `otp` | `qwer1234` | | `10103933108` | `otp` | `qwer1234` | :::tip Test users for Norwegian Bank ID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: 4. Upon successful authentication, Norwegian BankID redirects to the Redirect URI of your OIDC client. This is `https://oauth.tools/callback/code`. 3. In OAuth Tools, in **(3) Redeem Authorization Code**, click **Redeem Code**. After you redeem the authorisation code, you will find the **Access Token** and the **ID Token** in the pane on the right-hand side. In particular, the **ID Token** > **Payload** contains the JSON with the personal information of the end-user. **Payload example** ```json { "iss":"https:///auth/open", "nbf":1780326261, "iat":1780326261, "exp":1780326861, "aud":"", "amr":["external"], "at_hash":"WSabMjkG...coOtemlQClQ", "sid":"2D27D47B593142CD747F821ED20E7330", "sub":"mVyIHdx-vovALfhWgoVs...Hzbknv0BNH9AcIxZHhI4=", "auth_time":1780326258, "idp":"nbid", "nin":"01100844350", "nin_type":"BIRTH", "nin_issuing_country":"NO", "idp_issuer":"https://auth.current.bankid.no/auth/realms/current", "transaction_id":"8612c10c-30dd-0449-bc5e-25a3f8fdc47e", "sandbox":true, "acr":"high" } ``` ### 5. Call Userinfo endpoint :::tip Optional endpoint The `UserInfo` endpoint is part of the [OpenID Connect standard (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) and is designed to return claims about the authenticated user. ::: 1. In the left-side menu, select **Userinfo**. 3. In section **(1) Settings**, select **Authorization Code Flow: Access Token** from the dropdown menu. 4. Click the **Call Userinfo Endpoint** button. 5. The Userinfo is shown in the pane on the right-hand side. :::info Success! You have now tested an OIDC authentication flow using your OIDC client. You can explore more flow types and additional OIDC functionality on the [https://oauth.tools/](https://oauth.tools/) website. ::: --- ## Quick start guide(Quick-start) # Quick start guide Learn how to identify your end-users in a few steps. This quick start guide shows you how to: 1. Activate an eID in the Signicat Dashboard. 2. Test an authentication flow. 3. Configure an authentication protocol. 4. Initiate an authentication flow with a protocol. :::note Note For illustration purposes, we use Norwegian BankID as an example eID. The same steps apply to the other eIDs supported by Signicat. ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::info Domains and eIDs For this guide you can use a standard Signicat domain. It is important to note that certain eIDs may require you to add digital SSL certificates and custom domains for security purposes. You can learn more in the [eID-specific documentation](/docs/eid-hub/e-ids/). ::: ## Add an eID in the Dashboard First, you need to add and activate the eID in your Signicat account. To do this: 1. In the Signicat Dashboard, go to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. To add a new eID, select **Add new** in the top right. 3. Choose _Norwegian BankID_ from the list. To activate it, click **Add**. Now, you can view _Norwegian BankID_ set as "Active" in the list of eIDs. :::note Production account To activate an eID in a production account, you may need to first complete additional procedures. Learn more about these requirements in the [eID-specific documentation](/docs/eid-hub/e-ids/). ::: ## Test the eID Once you have activated an eID, you can already run a test authentication flow, directly from the Signicat Dashboard. Testing helps you to better understand the user experience with an eID. To test an authentication flow in the Signicat Dashboard, do the following: 1. Go to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** at the top right. 3. Optional: When more than one eID is active in your account, a list with all your eIDs is displayed by default. Choose _Norwegian BankID_. 4. Follow the steps on the Norwegian BankID site to authenticate with the following test credentials: - National ID number: `01100844350` or `10103933108` - One Time Code: `otp` - BankID password: `qwer1234` :::tip Test users for Norwegian BankID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: 5. Review the user data attributes returned by BankID. Once you have completed a test authentication, we display the user attributes of your test user. ## Connect with an authentication protocol The Signicat eID and Wallet Hub provides authentication *as a service*, thus acting as the single point of integration between your application and a selection of eIDs. To authenticate your end-users, you connect your application to the eID and Wallet Hub using an authentication protocol. :::note The role of Signicat Note that you only need to connect to the eID and Wallet Hub servers. In the background, Signicat handles the connection to the eIDs separately, therefore acting as a message broker between your application and the eIDs. ::: ### Choose a protocol The eID and Wallet Hub supports the following authentication protocols: - [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) - [SAML 2.0](/docs/eid-hub/saml-2-0/) - [Signicat's Authentication REST API](/docs/eid-hub/authentication-api/) When you build your integration, you need to implement your connection with one of these protocols. :::details Choosing a protocol You should choose a protocol based on what you prefer, what your application supports and what you want to achieve. OIDC and SAML are official identity standards, while the Authentication REST API is a solution developed and maintained by Signicat. The Signicat [Authentication REST API](/apis/eid-hub/) offers a lot of flexibility and supports _headless_ and _redirect_ integration flow(s) (grant type). If you want to use an official identity protocol, we recommend using OIDC. When choosing, consider the following: - SAML 2.0 is much more complex to implement on your side since it relies on XML schemas to transmit user information and usually requires a federation agent already in place. - OIDC is an industry standard that only focuses on authentication and based on the OAuth 2.0 standard. You send direct calls between services using REST and JSON, accessible through APIs. With OIDC you do not need to manage user sessions on your own (like with the Authentication REST API). ::: ## Build a connection To understand how to connect with an authentication protocol, select the corresponding tab below.

OpenID Connect (OIDC)

The following sections describe how to set up authentication with OIDC. Instructions are generic and agnostic of any programming language. For a more detailed guide with language-specific examples, see the [Code examples for OIDC](/docs/eid-hub/oidc/code-examples/). To get started with OIDC, follow these steps: 1. Register an OIDC client in the Signicat Dashboard 2. Find your Discovery and issuer URL 3. Build an authentication request You can find more details about each step below.

1. Register an OIDC client

Before you can start authenticating users, you must register an OIDC client application in the Signicat Dashboard. An OIDC client comes with a **Client ID**. Depending on the authentication grant type (flow) you want to implement, you may associate a secret to the client. To register your OIDC client application in the Signicat Dashboard, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Add client**. 3. Configure your OIDC client with these settings: - **Primary grant type**: Choose the grant type you want to implement. We strongly recommend **AuthorizationCode** (Authorization Code flow). Learn more about OIDC grant types in the to the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#Authentication) and the [OAuth 2.0 specification](https://oauth.net/2/grant-types/). - **Create client from template**: Optional. Allows you to use a template to prefill your client configuration. Skip this if you want to customise your configuration. - **Client name**: Enter a name for the client. - **Redirect URI**: Enter the URL where you want to redirect your end-user after they authenticate with an eID. Note that you can add several redirect URIs after you create the client. - **Scope**: Select the scopes for the type of data you want to retrieve with this client. `openid` is mandatory. `profile` and `nin` are necessary in most cases. You can see the definition of `profile` and other predefined scopes in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). You find scope definitions in the specific [eIDs](/docs/eid-hub/e-ids/) documentation. 4. Select **Create** to create the new client. Congratulations, you have created an OIDC client!

2. Find your Discovery and issuer URL

Depending on how you want to implement your app, you can find: - The discovery URL: `https:///auth/open/.well-known/openid-configuration`. For example, if your domain is `https://verybigcorp.signicat.com`, your discovery URL is `https://verybigcorp.signicat.com/auth/open/.well-known/openid-configuration`. - The issuer URL: `/auth/open/`. For example, your issuer URL would be `https://verybigcorp.signicat.com/auth/open/`.

3. Build an authorisation request

To start authenticating your end-users, your application must direct them to the authorisation endpoint (`https:///auth/open/connect/authorize`) with the appropriate parameters. At a minimum, your OIDC authorisation request must include: - **client_id**: The unique ID of your OIDC client that you registered in the Signicat Dashboard. - **response_type**: The OAuth response type that determines the authorisation flow and response parameters. Use `code` for the Authorization Code flow. - **redirect_uri**: The URL of your website or application where Signicat redirects end-users after they authenticate. - **scope**: Must include `openid` and any other scopes for attributes that the eID supports. - **state**: A random value that protects your application against Cross-Site Request Forgery (CSRF). - **nonce**: A random value to secure the integrity of your ID token. You need to compare the returned `nonce` claim with the value sent in the request. - **prompt**: Optional. Forces your end-users to re-authenticate every time, bypassing any active Single Sign-On (SSO) cookies or sessions. Example authorisation request (line breaks included for readability): ```http https:///auth/open/connect/authorize? &client_id=sandbox-example-client-123 &response_type=code &redirect_uri=https://myservice.example/redirect &scope=openid &acr_values= &state=af93kslz &nonce=bn28sjdp &prompt=login ``` Your next steps depend on the type of OIDC flow you want to use. After your end-users authenticate, you can retrieve the results from the **ID token** and from the **UserInfo** endpoints.

Next steps

This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about OIDC and exploring the eIDs documentation.
* [**OIDC**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs

SAML 2.0

This guide explains how you can exchange XML metadata files with Signicat to set up a SAML 2.0 connection. To learn more about integrating using SAML 2.0, see [Set up SAML](/docs/eid-hub/saml-2-0/saml-metadata.mdx).

How to exchange SAML metadata

To set up a secure connection over SAML, you must provide Signicat with a metadata file. :::info What is in the SAML metadata file? A metadata file contains information about the service provider (SP) and the identity provider (IdP) involved in an authentication process. For example, the metadata stores the URL of the server where to send the response after the authentication session. ::: To integrate your application with Signicat using SAML 2.0, you configure the metadata in the Signicat Dashboard. You can choose between these configuration options: - **Dynamic with URL**: You host the metadata in your server and share the metadata URL with Signicat. - **Static with Form**: You upload the metadata file in the Signicat Dashboard. If you don't have a metadata, you can fill in a form in the Dashboard and have Signicat generate (and store) the metadata file. To configure a dynamic metadata URL in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **URL** configuration method. 3. Fill in the configuration. You can find information about the fields in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat's metadata**.
URL configuration fields
:::warning Registering a new Metadata URL To fetch your metadata file, we first need to check that the URL is safe. Before adding a new Metadata URL, please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Metadata URL\* | The web address where you host the metadata. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. LoA contracts can be configured under **Level of assurance contracts**. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Response attribute mapping | You can choose to customise the name of the attributes received in the response body. | ::: :::tip Advanced configuration Learn more about advanced configuration in the [URL configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-url-configuration) section of the SAML 2.0 documentation. ::: To configure a static metadata Form in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **Form** configuration method. 3. If you've already created your metadata file, upload it here. If not, create the metadata using the form fields described in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat metadata**.
Form configuration fields
Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Entity ID\* | Unique identifier for the connection. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. See [Level of Assurance contracts](/docs/eid-hub/saml-2-0/saml-loa-contracts.mdx) for more information. | | Want assertions signed | If ticked, assertions will be signed. | | Use a transient format for the NameID | Tick this box if you only want a transient NameID.| | Include the SAML Assertion of the IdentityProvider if available | If the eIDs that you use are SAML-based, you may opt to receive the original SAML assertion of the eID. | | Encrypt assertion | If you want to receive an `EncryptedAssertion` instead of an `Assertion` for added security, select this option. Note that some eIDs require you to receive an `EncryptedAssertion`. | | Assertion consuming services\* | At least one assertion consuming service must be configured. Provide a location URL and a binding type (`REDIRECT`, `POST` or `ARTIFACT`). | | Single logout services | Enter the location URL and binding type (`REDIRECT`, `POST` or `ARTIFACT`) of any applicable single logout services. | | Artifact resolution services | Enter the location URL, binding type and index of any applicable artifact resolution services. | | Attribute consuming services | Enter name, index, description (optional) and at least one attribute | | Certificate\* | Upload all relevant certificates for the connection (at least one). Information about the certificates, such as issuer and expiration date, is displayed when they are uploaded. | | Client organisation | Enter organisation name, display name, and URL. | | Hosting party organisation | Provide organisation name, display name, and URL. | | Contact people | Provide details about the contact people in your organisation. In **Type of contact person**, specify whether they are part of support, a technical department, name, phone number, and more. | | Response attribute mappings | You can customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Select default eID rule | Select which eID rule to use by default. To add eID rules in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/). | ::: :::tip Advanced configuration Learn more about advanced configuration in the [Form configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-form-configuration) section of the SAML 2.0 documentation. :::

Metadata file example

Here is an example of a SAML 2.0 metadata file: ```xml XML_SIGNATURE KEY_NAME X509_ENCODED_CERTIFICATE ORG_NAME ORG_DISPLAY_NAME ORG_URL ``` After you have configured the SAML metadata in the Dashboard, you are ready to initialise a request for end-user authentication.

SAML authentication examples

When the end-user wants to authenticate to your services over a SAML connection, the service provider (your app) and the identity provider communicate by sending: 1. A request: `AuthnRequest` 2. A response: `AuthnResponse` Below, you can find examples of requests and responses. For more examples, see the [SAML examples](/docs/eid-hub/saml-2-0/saml-examples.mdx).

AuthnRequest example

The SAML `AuthnRequest` can be simple. You can always add more information in the request, but the request can be as minimal as the following example (POST binding): ```xml ENTITY_ID XML_SIGNATURE ``` The SAML `AuthnRequest` request needs to be encoded for transmission. Usually, it's compressed, then Base64-encoded and finally URL-encoded. Many SAML libraries handle this automatically.

Example authorisation URL

To initiate an authentication flow using SAML, you typically redirect the end-user to the authorisation URL. Depending on the SAML binding, you send the request in a different format. For example, for POST binding you can generate an authorization URL like this: ```curl POST https:///auth/saml/login ``` and pass the following in the body of the request: - `SAMLRequest` is your encoded `AuthnRequest` request. - `RelayState` is optional and can be used to retain state information to return to after authentication.

AuthnResponse example

Example of a SAML response `AuthnResponse` after the end-user logged in with eHerkenning: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE https:/*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y= ENTITY_ID Gerarda Josephina Kierkegaard Gerarda Josephina Kierkegaard email@example.com 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 24444001 819935177 urn:etoegang:DV:00000003244440010000:services:9121 cf1c1457-cc97-4b47-a324-25d1a97db3cb 24444002 Signicat Intermediary urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:00000003244440010000:entities:9713 ```

Next steps

This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about SAML 2.0 and exploring the eIDs documentation.
* [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains. * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs

Authentication REST API

The Authentication REST API allows you to connect to the eID and Wallet Hub and perform end-user identity verification and authentication through a REST API, where all request and response bodies are formatted in JSON.

Initial preparation

The Authentication REST API supports the OAuth 2.0 *client credentials* grant flow: you first exchange a client ID and a secret for an access token, then use the access token to authenticate the requests to the API endpoints. To learn how to connect to this API, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **Authentication REST API** for your API client. :::

Import the Postman collection

You can make calls to the Authentication REST API using our Postman collection. :::tip Testing only Note that Postman is a tool for testing and learning about APIs. You should not rely on Postman in production. ::: You can fork or import the Postman collection by clicking the button below: [Run In Postman](https://app.getpostman.com/run-collection/20756027-56b06e30-202c-43b6-8838-3eb0007ebb39?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D20756027-56b06e30-202c-43b6-8838-3eb0007ebb39%26entityType%3Dcollection%26workspaceId%3D3ea7a3cf-7777-4f42-b4e9-88876cfe660d) To start using the Postman collection, do the following: 1. Fork or import the Postman collection. 2. Open Postman and select the **Signicat Authentication REST API** collection. 3. In the Variables tab, edit the following variables: - `baseURL`: The base URL of the API. Set this to: `https://api.signicat.com/auth/rest`. - `oauth_scope`: The scope. Set this to: `signicat-api`. - `oauth_client_id`: The client ID of your API client. For example, this looks like `dev-red-pin-123`. - `oauth_client_secret`: The client secret associated to your API client. - `oauth_url`: The Authorisation URL. Set this to: `https://api.signicat.com/auth/open/connect/token`. 4. Save your variables by clicking the save icon or pressing Ctrl+S. Now, you are ready to obtain an access token using the variables you defined above.

Obtain an access token

To authorise requests to the API, you need to send an access token in your request. To obtain the access token with the Postman collection, do the following: 1. Select the Authorization tab. 2. Scroll to the bottom and select **Get New Access Token**. 3. If the request was successful, review the Access Token and select **Use Token**. You have now obtained a token to authenticate to the API. When calling an API endpoint, you supply the access token in the HTTP `Authorization` header of your request. You can always review your token in **Authorization > Token**. **Note:** Tokens have a default expiry date. If a token expires, repeat the steps above to request a new token.

Create an authentication session

To begin an authentication flow, your app needs to direct the end-user to an eID, such as Norwegian BankID. To obtain the authorization URL where to redirect the end-user to authenticate, you send a POST request to the **Create a new session** endpoint with the appropriate parameters in the body of the request. The body of the request might look like this: ```json { "flow": "redirect", "requestedAttributes": [ "name", "dateOfBirth", "nin", ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "allowedProviders": [ "nbid" ], } ``` To begin an authentication flow using the Postman collection, do the following: 1. In the left menu, expand the collection and select the **Create a new session** endpoint. 2. In the endpoint window, select **Send** to send the request. 3. In the response window, select the **Body** tab to view the response payload. 4. Copy and paste the `authenticationUrl` link in your browser to start an authentication session with the eID. In this case, Norwegian BankID. When adding login to your application, you will redirect the end-user to the `authenticationUrl`.

Authenticate the end-user

You need a test user to complete the authentication. For example, you can use the following credentials for Norwegian BankID: :::CustomTable{columnWidths="33% 33% 33%"} | National identity number | One-time password | Password | | :----------------------- | :---------------- | :--------- | | `01100844350` | `otp` | `qwer1234` | | `10103933108` | `otp` | `qwer1234` | ::: :::tip Test users for Norwegian BankID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: After completing the authentication flow, you can retrieve the response from successful authentication.

Get the authentication session status

When using the API, you can check the status of the authentication session at any stage. When the end-user authenticates successfully, you receive the user data attributes in the response. To do this: 1. In the left menu, expand the **id** folder and open the **Get session status** endpoint. 2. To check the session status, select **Send**. This sends an HTTP GET request using the session ID obtained from the **Create a new session** endpoint. 3. Inspect the response in the **Body** tab of the response window. If the authentication was successful (`"status": "SUCCESS"`), you find the end-user data attributes in the `subject` field. You have now completed an authentication flow using the Authentication REST API!

Next steps

This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about the Authentication REST API and exploring the eIDs documentation.
* [**Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users. * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs
For information about the available endpoints and properties, as well as sample requests and responses, see the Authentication REST API reference:
* [**Authentication REST API**](/apis/eid-hub/): Configure your Authentication REST API
--- ## Oidc OpenID Connect (OIDC) The following sections describe how to set up authentication with OIDC. Instructions are generic and agnostic of any programming language. For a more detailed guide with language-specific examples, see the [Code examples for OIDC](/docs/eid-hub/oidc/code-examples/). To get started with OIDC, follow these steps: 1. Register an OIDC client in the Signicat Dashboard 2. Find your Discovery and issuer URL 3. Build an authentication request You can find more details about each step below. 1. Register an OIDC client Before you can start authenticating users, you must register an OIDC client application in the Signicat Dashboard. An OIDC client comes with a **Client ID**. Depending on the authentication grant type (flow) you want to implement, you may associate a secret to the client. To register your OIDC client application in the Signicat Dashboard, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Add client**. 3. Configure your OIDC client with these settings: - **Primary grant type**: Choose the grant type you want to implement. We strongly recommend **AuthorizationCode** (Authorization Code flow). Learn more about OIDC grant types in the to the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#Authentication) and the [OAuth 2.0 specification](https://oauth.net/2/grant-types/). - **Create client from template**: Optional. Allows you to use a template to prefill your client configuration. Skip this if you want to customise your configuration. - **Client name**: Enter a name for the client. - **Redirect URI**: Enter the URL where you want to redirect your end-user after they authenticate with an eID. Note that you can add several redirect URIs after you create the client. - **Scope**: Select the scopes for the type of data you want to retrieve with this client. `openid` is mandatory. `profile` and `nin` are necessary in most cases. You can see the definition of `profile` and other predefined scopes in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). You find scope definitions in the specific [eIDs](/docs/eid-hub/e-ids/) documentation. 4. Select **Create** to create the new client. Congratulations, you have created an OIDC client! 2. Find your Discovery and issuer URL Depending on how you want to implement your app, you can find: - The discovery URL: `https:///auth/open/.well-known/openid-configuration`. For example, if your domain is `https://verybigcorp.signicat.com`, your discovery URL is `https://verybigcorp.signicat.com/auth/open/.well-known/openid-configuration`. - The issuer URL: `/auth/open/`. For example, your issuer URL would be `https://verybigcorp.signicat.com/auth/open/`. 3. Build an authorisation request To start authenticating your end-users, your application must direct them to the authorisation endpoint (`https:///auth/open/connect/authorize`) with the appropriate parameters. At a minimum, your OIDC authorisation request must include: - **client_id**: The unique ID of your OIDC client that you registered in the Signicat Dashboard. - **response_type**: The OAuth response type that determines the authorisation flow and response parameters. Use `code` for the Authorization Code flow. - **redirect_uri**: The URL of your website or application where Signicat redirects end-users after they authenticate. - **scope**: Must include `openid` and any other scopes for attributes that the eID supports. - **state**: A random value that protects your application against Cross-Site Request Forgery (CSRF). - **nonce**: A random value to secure the integrity of your ID token. You need to compare the returned `nonce` claim with the value sent in the request. - **prompt**: Optional. Forces your end-users to re-authenticate every time, bypassing any active Single Sign-On (SSO) cookies or sessions. Example authorisation request (line breaks included for readability): ```http https:///auth/open/connect/authorize? &client_id=sandbox-example-client-123 &response_type=code &redirect_uri=https://myservice.example/redirect &scope=openid &acr_values= &state=af93kslz &nonce=bn28sjdp &prompt=login ``` Your next steps depend on the type of OIDC flow you want to use. After your end-users authenticate, you can retrieve the results from the **ID token** and from the **UserInfo** endpoints. Next steps This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about OIDC and exploring the eIDs documentation. * [**OIDC**](/docs/eid-hub/oidc/): Find out more about OIDC, the authentication protocol based on the OAuth 2.0 protocol * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs --- ## Restapi Authentication REST API The Authentication REST API allows you to connect to the eID and Wallet Hub and perform end-user identity verification and authentication through a REST API, where all request and response bodies are formatted in JSON. Initial preparation The Authentication REST API supports the OAuth 2.0 *client credentials* grant flow: you first exchange a client ID and a secret for an access token, then use the access token to authenticate the requests to the API endpoints. To learn how to connect to this API, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **Authentication REST API** for your API client. ::: Import the Postman collection You can make calls to the Authentication REST API using our Postman collection. :::tip Testing only Note that Postman is a tool for testing and learning about APIs. You should not rely on Postman in production. ::: You can fork or import the Postman collection by clicking the button below: [](https://app.getpostman.com/run-collection/20756027-56b06e30-202c-43b6-8838-3eb0007ebb39?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D20756027-56b06e30-202c-43b6-8838-3eb0007ebb39%26entityType%3Dcollection%26workspaceId%3D3ea7a3cf-7777-4f42-b4e9-88876cfe660d) To start using the Postman collection, do the following: 1. Fork or import the Postman collection. 2. Open Postman and select the **Signicat Authentication REST API** collection. 3. In the Variables tab, edit the following variables: - `baseURL`: The base URL of the API. Set this to: `https://api.signicat.com/auth/rest`. - `oauth_scope`: The scope. Set this to: `signicat-api`. - `oauth_client_id`: The client ID of your API client. For example, this looks like `dev-red-pin-123`. - `oauth_client_secret`: The client secret associated to your API client. - `oauth_url`: The Authorisation URL. Set this to: `https://api.signicat.com/auth/open/connect/token`. 4. Save your variables by clicking the save icon or pressing Ctrl+S. Now, you are ready to obtain an access token using the variables you defined above. Obtain an access token To authorise requests to the API, you need to send an access token in your request. To obtain the access token with the Postman collection, do the following: 1. Select the Authorization tab. 2. Scroll to the bottom and select **Get New Access Token**. 3. If the request was successful, review the Access Token and select **Use Token**. You have now obtained a token to authenticate to the API. When calling an API endpoint, you supply the access token in the HTTP `Authorization` header of your request. You can always review your token in **Authorization > Token**. **Note:** Tokens have a default expiry date. If a token expires, repeat the steps above to request a new token. Create an authentication session To begin an authentication flow, your app needs to direct the end-user to an eID, such as Norwegian BankID. To obtain the authorization URL where to redirect the end-user to authenticate, you send a POST request to the **Create a new session** endpoint with the appropriate parameters in the body of the request. The body of the request might look like this: ```json { "flow": "redirect", "requestedAttributes": [ "name", "dateOfBirth", "nin", ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "allowedProviders": [ "nbid" ], } ``` To begin an authentication flow using the Postman collection, do the following: 1. In the left menu, expand the collection and select the **Create a new session** endpoint. 2. In the endpoint window, select **Send** to send the request. 3. In the response window, select the **Body** tab to view the response payload. 4. Copy and paste the `authenticationUrl` link in your browser to start an authentication session with the eID. In this case, Norwegian BankID. When adding login to your application, you will redirect the end-user to the `authenticationUrl`. Authenticate the end-user You need a test user to complete the authentication. For example, you can use the following credentials for Norwegian BankID: :::CustomTable{columnWidths="33% 33% 33%"} | National identity number | One-time password | Password | | :----------------------- | :---------------- | :--------- | | `01100844350` | `otp` | `qwer1234` | | `10103933108` | `otp` | `qwer1234` | ::: :::tip Test users for Norwegian BankID Pre-generated test users for Norwegian BankID may become unavailable after a series of failed attempts. If this happens, you can [generate more test users](/identity-methods/nbid/test.mdx#order-test-user). ::: After completing the authentication flow, you can retrieve the response from successful authentication. Get the authentication session status When using the API, you can check the status of the authentication session at any stage. When the end-user authenticates successfully, you receive the user data attributes in the response. To do this: 1. In the left menu, expand the **id** folder and open the **Get session status** endpoint. 2. To check the session status, select **Send**. This sends an HTTP GET request using the session ID obtained from the **Create a new session** endpoint. 3. Inspect the response in the **Body** tab of the response window. If the authentication was successful (`"status": "SUCCESS"`), you find the end-user data attributes in the `subject` field. You have now completed an authentication flow using the Authentication REST API! Next steps This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about the Authentication REST API and exploring the eIDs documentation. * [**Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users. * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs For information about the available endpoints and properties, as well as sample requests and responses, see the Authentication REST API reference: * [**Authentication REST API**](/apis/eid-hub/): Configure your Authentication REST API --- ## Saml2 With Form To configure a static metadata Form in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **Form** configuration method. 3. If you've already created your metadata file, upload it here. If not, create the metadata using the form fields described in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat metadata**. Form configuration fields Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Entity ID\* | Unique identifier for the connection. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. See [Level of Assurance contracts](/docs/eid-hub/saml-2-0/saml-loa-contracts.mdx) for more information. | | Want assertions signed | If ticked, assertions will be signed. | | Use a transient format for the NameID | Tick this box if you only want a transient NameID.| | Include the SAML Assertion of the IdentityProvider if available | If the eIDs that you use are SAML-based, you may opt to receive the original SAML assertion of the eID. | | Encrypt assertion | If you want to receive an `EncryptedAssertion` instead of an `Assertion` for added security, select this option. Note that some eIDs require you to receive an `EncryptedAssertion`. | | Assertion consuming services\* | At least one assertion consuming service must be configured. Provide a location URL and a binding type (`REDIRECT`, `POST` or `ARTIFACT`). | | Single logout services | Enter the location URL and binding type (`REDIRECT`, `POST` or `ARTIFACT`) of any applicable single logout services. | | Artifact resolution services | Enter the location URL, binding type and index of any applicable artifact resolution services. | | Attribute consuming services | Enter name, index, description (optional) and at least one attribute | | Certificate\* | Upload all relevant certificates for the connection (at least one). Information about the certificates, such as issuer and expiration date, is displayed when they are uploaded. | | Client organisation | Enter organisation name, display name, and URL. | | Hosting party organisation | Provide organisation name, display name, and URL. | | Contact people | Provide details about the contact people in your organisation. In **Type of contact person**, specify whether they are part of support, a technical department, name, phone number, and more. | | Response attribute mappings | You can customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Select default eID rule | Select which eID rule to use by default. To add eID rules in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/). | ::: :::tip Advanced configuration Learn more about advanced configuration in the [Form configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-form-configuration) section of the SAML 2.0 documentation. ::: --- ## Saml2 With Url To configure a dynamic metadata URL in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **URL** configuration method. 3. Fill in the configuration. You can find information about the fields in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat's metadata**. URL configuration fields :::warning Registering a new Metadata URL To fetch your metadata file, we first need to check that the URL is safe. Before adding a new Metadata URL, please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Metadata URL\* | The web address where you host the metadata. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. LoA contracts can be configured under **Level of assurance contracts**. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Response attribute mapping | You can choose to customise the name of the attributes received in the response body. | ::: :::tip Advanced configuration Learn more about advanced configuration in the [URL configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-url-configuration) section of the SAML 2.0 documentation. ::: --- ## Saml2 SAML 2.0 This guide explains how you can exchange XML metadata files with Signicat to set up a SAML 2.0 connection. To learn more about integrating using SAML 2.0, see [Set up SAML](/docs/eid-hub/saml-2-0/saml-metadata.mdx). How to exchange SAML metadata To set up a secure connection over SAML, you must provide Signicat with a metadata file. :::info What is in the SAML metadata file? A metadata file contains information about the service provider (SP) and the identity provider (IdP) involved in an authentication process. For example, the metadata stores the URL of the server where to send the response after the authentication session. ::: To integrate your application with Signicat using SAML 2.0, you configure the metadata in the Signicat Dashboard. You can choose between these configuration options: - **Dynamic with URL**: You host the metadata in your server and share the metadata URL with Signicat. - **Static with Form**: You upload the metadata file in the Signicat Dashboard. If you don't have a metadata, you can fill in a form in the Dashboard and have Signicat generate (and store) the metadata file. To configure a dynamic metadata URL in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **URL** configuration method. 3. Fill in the configuration. You can find information about the fields in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat's metadata**.
URL configuration fields
:::warning Registering a new Metadata URL To fetch your metadata file, we first need to check that the URL is safe. Before adding a new Metadata URL, please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Metadata URL\* | The web address where you host the metadata. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. LoA contracts can be configured under **Level of assurance contracts**. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Response attribute mapping | You can choose to customise the name of the attributes received in the response body. | ::: :::tip Advanced configuration Learn more about advanced configuration in the [URL configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-url-configuration) section of the SAML 2.0 documentation. ::: To configure a static metadata Form in your account, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **Add new**. 2. Select the **Form** configuration method. 3. If you've already created your metadata file, upload it here. If not, create the metadata using the form fields described in the table below. 4. Select **Add** to save the configuration. 5. To download the Signicat metadata file in XML format, select **Get Signicat metadata**.
Form configuration fields
Required fields are marked with an asterisk (\*). :::CustomTable{columnWidths="25% 75%"} | Field name | Description | |:-------------------------------|:------------| | Name\* | Name of the connection. | | Application URL | URL of your application. | | Entity ID\* | Unique identifier for the connection. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. See [Level of Assurance contracts](/docs/eid-hub/saml-2-0/saml-loa-contracts.mdx) for more information. | | Want assertions signed | If ticked, assertions will be signed. | | Use a transient format for the NameID | Tick this box if you only want a transient NameID.| | Include the SAML Assertion of the IdentityProvider if available | If the eIDs that you use are SAML-based, you may opt to receive the original SAML assertion of the eID. | | Encrypt assertion | If you want to receive an `EncryptedAssertion` instead of an `Assertion` for added security, select this option. Note that some eIDs require you to receive an `EncryptedAssertion`. | | Assertion consuming services\* | At least one assertion consuming service must be configured. Provide a location URL and a binding type (`REDIRECT`, `POST` or `ARTIFACT`). | | Single logout services | Enter the location URL and binding type (`REDIRECT`, `POST` or `ARTIFACT`) of any applicable single logout services. | | Artifact resolution services | Enter the location URL, binding type and index of any applicable artifact resolution services. | | Attribute consuming services | Enter name, index, description (optional) and at least one attribute | | Certificate\* | Upload all relevant certificates for the connection (at least one). Information about the certificates, such as issuer and expiration date, is displayed when they are uploaded. | | Client organisation | Enter organisation name, display name, and URL. | | Hosting party organisation | Provide organisation name, display name, and URL. | | Contact people | Provide details about the contact people in your organisation. In **Type of contact person**, specify whether they are part of support, a technical department, name, phone number, and more. | | Response attribute mappings | You can customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Select default eID rule | Select which eID rule to use by default. To add eID rules in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/). | ::: :::tip Advanced configuration Learn more about advanced configuration in the [Form configuration](/docs/eid-hub/saml-2-0/saml-metadata.mdx#add-form-configuration) section of the SAML 2.0 documentation. ::: Metadata file example Here is an example of a SAML 2.0 metadata file: ```xml XML_SIGNATURE KEY_NAME X509_ENCODED_CERTIFICATE ORG_NAME ORG_DISPLAY_NAME ORG_URL ``` After you have configured the SAML metadata in the Dashboard, you are ready to initialise a request for end-user authentication. SAML authentication examples When the end-user wants to authenticate to your services over a SAML connection, the service provider (your app) and the identity provider communicate by sending: 1. A request: `AuthnRequest` 2. A response: `AuthnResponse` Below, you can find examples of requests and responses. For more examples, see the [SAML examples](/docs/eid-hub/saml-2-0/saml-examples.mdx). AuthnRequest example The SAML `AuthnRequest` can be simple. You can always add more information in the request, but the request can be as minimal as the following example (POST binding): ```xml ENTITY_ID XML_SIGNATURE ``` The SAML `AuthnRequest` request needs to be encoded for transmission. Usually, it's compressed, then Base64-encoded and finally URL-encoded. Many SAML libraries handle this automatically. Example authorisation URL To initiate an authentication flow using SAML, you typically redirect the end-user to the authorisation URL. Depending on the SAML binding, you send the request in a different format. For example, for POST binding you can generate an authorization URL like this: ```curl POST https:///auth/saml/login ``` and pass the following in the body of the request: - `SAMLRequest` is your encoded `AuthnRequest` request. - `RelayState` is optional and can be used to retain state information to return to after authentication. AuthnResponse example Example of a SAML response `AuthnResponse` after the end-user logged in with eHerkenning: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE https:/*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y= ENTITY_ID Gerarda Josephina Kierkegaard Gerarda Josephina Kierkegaard email@example.com 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 24444001 819935177 urn:etoegang:DV:00000003244440010000:services:9121 cf1c1457-cc97-4b47-a324-25d1a97db3cb 24444002 Signicat Intermediary urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:00000003244440010000:entities:9713 ``` Next steps This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about SAML 2.0 and exploring the eIDs documentation. * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains. * [**Supported eIDs**](/identity-methods/): View and learn how to integrate with the eIDs --- ## How it works(Risk-indicator) The Authentication Risk Indicator analyses specific attributes to detect whether an authentication session is likely to represent malicious or suspicious activity. Our risk engine supports customised rules that you can configure in order to perform an assessment in line with your security requirements. During an authentication session, the risk engine performs a data-driven risk assessment to determine the risk level based on information such as device, network and behavioural patterns. After the authentication completes, you receive a risk rating that indicates the level of anomalous activity detected. The value can be low, medium, or high. The insights you receive from the Authentication Risk Indicator allow you to mitigate malicious threats promptly and define follow-up actions before granting access to your end-users. :::note Note The Authentication Risk Indicator is intended for use as a supplementary tool and should not be solely relied upon when making risk decisions. ::: ## Risk data The Authentication Risk Indicator gathers and analyses several device, network and behavioural attributes from an authentication session. Data availability varies depending on the eID method used for authentication. If available, Signicat calculates the risk rating using data such as user's IP address, geolocation and number of failed attempts. {/* :::CustomTable{columnWidths="25% 75%"} | Attributes | Description | |------------------------|---------------------------------------------| | IP address | Source network address used for authentication. Allows to detect proxies and anomalous login patterns. | | Geolocation | Approximate physical location derived from IP. Allows to flag unusual or high-risk regions. New locations are flagged on the first login and receive a low risk score thereafter. | | Number of failed attempts | Count of recent failed attempts since last successful authentication, indicating possible brute-force or credential-stuffing activity.| | User-agent | Browser and device signature, supporting the detection of inconsistencies. | | App device type | Category of device (mobile, tablet, desktop). Allows to spot unexpected device changes. | | Timestamps of previous authentication sessions | Records of login times. Allows to analyse behavioural patterns and identify unusual activity. | ::: */} :::info Other authentication information The Authentication Risk Indicator is in active development; more risk attributes will be available soon. ::: :::note Is this data returned in the response? In the response you only receive the risk rating without the underlying raw data used for the calculation. This is to comply with GDPR and privacy regulations. ::: ## Set the rules The Authentication Risk Indicator allows you to configure risk-prevention rules to identify suspicious or risky activity. Risk rules have customised logic and definitions, based on lambda expressions, used to determine the risk level of an authentication session. For example, you could create a basic rule to count the number of failed login attempts for a specific user within the last 15 minutes. You would then determine the risk level based on the number of failed attempts over time, say high risk above 10 attempts. {/* You can create groups of multiple rules to handle specific fraud detection needs and different scenarios by using [Risk policies](#risk-policies). */} :::info Can rules encode follow-up actions? The rules you define are only used to calculate the risk rating of an authentication. After you receive the risk rating for an authentication session, you should decide which action (if any) to take based on the result of the Risk Indicator. Then, you should handle the logic on your application side. For example, if a risk is returned as high, you should decide whether the transaction should be cancelled, completed, or if some other follow-up verification steps should occur. ::: {/* ## Risk policies With the Authentication Risk Indicator, you can configure policies tailored to different fraud detection scenarios. Each policy may contain several rules and handle a single eID. For instance, you could have a policy to group and evaluate together: - A rule to check for a high number of failed login attempts - A rule to track the geolocation of the user device across session. Then, you can add weights to assign different importance to each rule. Weights are factored in when calculating the final risk rating, as explained below. */} ## Risk rating The risk rating you receive can have one of the following values: - Low - Medium - High High is the strongest indication of an authentication with anomalous activity. ### How the risk rating is calculated When configuring the Risk Indicator, you can choose which algorithm to use to calculate the risk rating: - **Max value**: Returns the highest risk level found across all rules. For example, if one rule/parameter returns a high value, the Risk Indicator will return a "high" risk rating, regardless of other ratings. - **Weighted average**. Returns the average value of all ratings from different rules, after applying the respective weights. By default, all rules have equal weights, but you can customise the weights to suit your individual risk profile. ## Types of risk evaluation The Signicat eID and Wallet Hub supports two different types of risk assessment: - **Risk engine evaluation** - **Third-party eID processing and evaluation** When you activate the Authentication Risk Indicator and request a risk assessment for an authentication session, you always receive the Signicat risk engine evaluation and, optionally, also the third-party assessment from the eID. ### Risk engine evaluation The **Risk engine evaluation** is designed by Signicat and it allows you to set customised rules and settings. When you activate this product, one of our onboarding managers will support you with setting up different rules and risk rating options. {/* The Signicat **Risk engine evaluation** allows you to configure customised rules and settings in the Signicat Dashboard. Here, you can manage your policies and choose among different risk rating options. */} ### Third-party eID processing and evaluation In addition, certain eID methods provide their own risk evaluation, we refer to this as **Third-party eID evaluation**. For example, Swedish BankID (SBID) provides a risk indicator in the authentication response. We pass this risk indicator to you in the authentication response. Note that this risk indicator is independent of Signicat's in-house processed risk rating. :::note Are these different values? Note that the risk ratings returned by the Signicat Risk engine evaluation and the third-party eID processing evaluation are calculated differently and might therefore have different values. ::: --- ## Authentication Risk Indicator The Authentication Risk Indicator assists you with preventing identity-related fraud by identifying high-risk authentications. This add-on tool relies on a data-driven risk engine to determine how a user authentication is likely to represent anomalous or malicious activity. Signicat assigns a risk level—low, medium, or high—to each authentication session by applying a set of rules to process data such as: - The IP address and geolocation of the user - Timestamps of previous authentications - Record of failed transactions - Device agent Using this information, you can define customised rules to handle different risk scenarios and prevent identity-related fraud. Learn more about the features of the Risk Indicator in the [How it works](/docs/eid-hub/risk-indicator/how-it-works.mdx) page. :::note Which eIDs are supported? We are in the process of rolling out the Risk Indicator for all eIDs. Currently, this feature is available for: - [Swedish BankID](/identity-methods/sbid/) - Third-party eID processing and evaluation - [Danish MitID](/identity-methods/mitid/) - Signicat risk engine evaluation ::: :::note Additional costs apply This is a paid add-on feature to the Signicat eID and Wallet Hub. Please note that additional costs will apply. We recommend that you contact one of our onboarding managers or [Signicat Sales](https://www.signicat.com/contact/contact-sales) for more details on pricing and activation. ::: ## Get started * [**Quick start guide**](/docs/eid-hub/risk-indicator/quick-start-guide): Get started with the Risk Indicator * [**How it works**](/docs/eid-hub/risk-indicator/how-it-works): Learn about the concepts of the Risk Indicator ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Quick start guide(Risk-indicator) # Quick start guide Learn how to set up safe authentications using the Authentication Risk Indicator. This quick start guide shows you how to: 1. Prepare for testing authentications with Authentication Risk Indicator. 2. Craft your authentication request. 3. Perform end-user authentication. 4. Review the risk assessment in the response. :::note Additional costs apply This is a paid add-on feature to the Signicat eID and Wallet Hub. Please note that additional costs will apply. We recommend that you contact one of our onboarding managers or [Signicat Sales](https://www.signicat.com/contact/contact-sales) for more details on pricing and activation. ::: ## Prerequisites The Authentication Risk Indicator is an add-on to the Signicat eID Hub. To start using this feature, you first need to have completed the following preparations: 1. Follow the [Quick start guide](/docs/eid-hub/quick-start/index.mdx) for the eID and Wallet Hub. In particular, make sure you: 1. Get started with the Signicat Dashboard. 2. Add an eID. 3. Set up an authentication protocol. 2. Activate the Authentication Risk Indicator with an onboarding manager or [Signicat Sales](https://www.signicat.com/contact/contact-sales). ## End-user authentication flow Below, you can find a sequence diagram that outlines how a typical authentication flow with the Risk Indicator works. ```mermaid sequenceDiagram participant User as End-User participant Client as Your Application (Client) participant Auth as Signicat Auth Server User->>Client: Access protected resource / start authentication Client->>Auth: Send Authentication request with Risk Indicator attribute Auth->>User: Present Login & Optional Consent User->>Auth: Submit Credentials / Factors Auth->>Client: Return Authentication Result (token/assertion/session info) Client->>Auth: Optional call for additional user attributes Auth->>Client: Attributes Response (includes risk rating) Client->>Client: Enforce risk rules & establish session Client->>User: Access Granted ``` ### 1. Authentication request To obtain a risk evaluation of an end-user authentication with the Authentication Risk Indicator, you need to specify a parameter in the authentication request. How you specify the risk parameter varies per authentication protocol. Below, select the tab of the authentication protocol you use to connect your application. #### Request example To start an end-user authentication with OIDC, you direct the end-user to the authorisation endpoint (`https:///auth/open/connect/authorize`) with the appropriate set of parameters. To request the Authentication Risk Indicator for an authentication session, you need to provide the `risk` scope in the authentication request. ``` scope=openid risk ``` The example below shows what an authentication request could look like. ```curl {5} title="Example: Authentication request with risk scope" https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri=https://myservice.example/redirect &scope=openid%20risk &code_challenge=ABC123 &code_challenge_method=S256 &state=12345 &nonce=678910 ``` When using SAML, you can request attributes in a few different ways, as explained in the [SAML Requested Attributes](/docs/eid-hub/saml-2-0/saml-requested-attributes.mdx) documentation. To request the Authentication Risk Indicator for an authentication session, you need to provide the `risk` attribute in your preferred SAML 2.0 way. To add the `risk` attribute in your `AuthnRequest`, you need to specify it using the `RequestedAttributes` element, as shown below: ```xml {4} title="Example: AuthnRequest with risk attribute" ``` To start an end-user authentication with the Signicat REST API, you first send a request to the [CreateSession](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint with the appropriate set of parameters in the payload. To request the Authentication Risk Indicator for an authentication session, you need to provide the `risk` scope in the `requestedAttributes` property in the payload of authentication request. ```json {5} title="Example: requestedAttributes with risk scope" ... "flow": "redirect", "requestedAttributes": [ "idpId", "risk", ], ... ``` The example below shows what an authentication request could look like. ```http {12} title="Example: Create session request with risk scope" POST /auth/rest/sessions HTTP/1.1 Host: Content-Type: application/json Accept: application/json Authorization: Bearer eyJ...YNzg Content-Length: 235 { "flow": "redirect", "requestedAttributes": [ "idpId", "risk" ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, } ``` In the response, you receive the `authenticationUrl` where to redirect the end-user to start an authentication session. ```json title="Example: Authentication URL with risk scope" { "id": "c99e17e2-b124-f549-a88c-408f8e555d31", "accountId": "", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=78b6b34..b4377d4c&transactionId=f4d..Ad1", "status": "CREATED", "callbackUrls": { "success": "https://example.com:443/success?sessionId=5b8b2527-4d38-4256-a2c9-ffabd51db776", "abort": "https://example.com:443/abort?sessionId=5b8b2527-4d38-4256-a2c9-ffabd51db776", "error": "https://example.com:443/error?sessionId=5b8b2527-4d38-4256-a2c9-ffabd51db776" }, "flow": "redirect", "requestedAttributes": [ "idpId", "risk", ], "sessionLifetime": 1200, "expiresAt": "2025-12-02T12:47:30.0635565+00:00" } ``` ### 2. User authenticates at the eID When the end-user navigates to the authentication URL, Signicat redirects the session to the eID method of choice. Here, the eID presents: - Login screen - Optional multi-factor challenge - Optional consent screen (including the custom risk scope) If the user consents and authentication succeeds, the eID redirects the user back to your `redirect_uri`. You can then proceed to retrieve the authentication response and evaluate its content to assess the risk rating calculated. ### 3. Receive the authentication response #### Response example After an authentication session has been completed, your receive a response with authorisation code. You need to exchange this code in the request to the `/token` endpoint to obtain: - **Access Token**: Authorises access to APIs or UserInfo - **ID Token**: Proves the user has authenticated - **Refresh Token** The token response contains an ID token. This token contains the core user identity claims for the scopes you requested in the authentication request, including those specific to the Authentication Risk Indicator. After you read and validate the ID Token, you can retrieve the risk rating calculated by the risk engine, as part of the risk scope: ```json title="Example: Authentication response with risk rating" "risk": { "selfEvaluation": { "riskValue": "medium" } } ``` **Third-party eID processing and evaluation** Optionally, if the eID method used for authentication supports risk rating analysis, you will also receive a `thirdPartyEvaluation` object that contains: - **riskValue**: Rating calculated by the third-party eID service. - **source**: Name of the eID. ```json title="Example: Authentication response with third-party risk rating" "risk": { "thirdPartyEvaluation": { "riskValue": "high", "source": "sbid" } } ``` When the end-user completes the authentication successfully, the response contains the end-user identity data together with the risk rating calculated by the risk engine. Authentication response example with risk rating (edited for readability) ```xml {4} title="Example: AuthnRequest with risk attribute" https://*YOUR_SIGNICAT_DOMAIN*/auth/saml medium ``` **Third-party eID processing and evaluation** Optionally, if the eID method used for authentication supports risk rating analysis, you will also receive a `thirdPartyEvaluation` object that contains: - **riskValue**: Rating calculated by the third-party eID service. - **source**: Name of the eID. ```xml {4} title="Example: Authentication response with third-party risk rating" high sbid ``` During the authentication process, you can check the status of the session to track whether the flow has started, failed or completed. To get the status of a session, send a GET request to `https://api.signicat.com/auth/rest/sessions/{id}`, where the `id` is provided in the response you received when you created the session. In the response example above, the `id` is `c99e17e2-b124-f549-a88c-408f8e555d31` so the request would be `https://api.signicat.com/auth/rest/sessions/c99e17e2-b124-f549-a88c-408f8e555d31`. When the end-user completes the authentication successfully, the response has status is `SUCCESS` and contains the end-user identity data together with the risk rating calculated by the risk engine. Authentication response example with risk rating (edited for readability): ```json {9-13} title="Example: Authentication response with risk rating" { "id": "c99e17e2-b124-f549-a88c-408f8e555d31", "accountId": "", "status": "SUCCESS", "provider": "mitid", "subject": { "id": "X6hYg...NQ=", "idpId": "5D6C8...63066F", "risk": { "selfEvaluation": { "riskValue": "medium" }, }, }, "flow": "redirect", "requestedAttributes": [ "idpId", "risk", ], } ``` **Third-party eID processing and evaluation** Optionally, if the eID method used for authentication supports risk rating analysis, you will also receive a `thirdPartyEvaluation` object that contains: - **riskValue**: Rating calculated by the third-party eID service. - **source**: Name of the eID. ```json title="Example: Authentication response with third-party risk rating" "risk": { "thirdPartyEvaluation": { "riskValue": "high", "source": "sbid" } } ``` ### 4. Use the risk rating in your policy Depending on the returned rating, on your application side you might want to implement an access restriction policy, such as: - Allow login normally - Require additional verification (MFA) - Require stepped-up authentication - Flag suspicious activity - Restrict access Once your application validates the ID Token and verifies any identity-fraud checks, you may redirect your end-users to start an authenticated session in your digital service. --- ## SAML 2.0 Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorisation data between security domains. Typically, this exchange happens between an identity provider like Signicat and a service provider (your organisation). SAML is a product of the [OASIS Security Services Technical Committee](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security). SAML is an industry standard protocol for identity management and is supported by most of the biggest actors in the computer industry. For detailed information about SAML 2.0, relevant technical terms and access to several white papers, visit [this page](https://www.oasis-open.org/specs/index.php#samlv2.0) on the OASIS website. Signicat supports the SAML 2.0 standard fully, through a gateway referred to as the 'SAML gateway' or 'SAML2 gateway'. If you are using an identity federation service such as Microsoft AD FS or Oracle Identity Federation, then you are most likely interested in Signicat's SAML2 gateway. ## Authentication using SAML 2.0 Signicat's SAML2 gateway provides a solution for end-user authentication over the SAML 2.0 protocol between two parties: you, a service provider (SP), and Signicat, as the message broker to the identity providers (IdP). The SAML2 gateway is integrated within the Signicat eID and Wallet Hub, which means that you can perform authentications over the SAML 2.0 protocol with all the eIDs supported by Signicat. In this scenario, Signicat acts as the single point of integration between your application and the third-party identity providers (also known as eIDs). To get started with end-user authentication using the SAML 2.0, go to the [Set up SAML](/docs/eid-hub/saml-2-0/saml-metadata) guide. ### Using a federation service If you rely on a SAML 2.0 federation service to establish connections with Signicat, you need to configure Signicat also in your federation service. Examples of such federation services are: - Microsoft Active Directory Federation Services (AD FS) - Oracle Identity Federation (OIF) - [SimpleSAML](https://simplesamlphp.org/), a PHP-based solution developed through a project led by UNINETT in Norway. The IdP, and other communication parameters between SP and IdP, should be configured in this SAML 2.0 federation service. After the SAML 2.0 configuration is established, you will need to define the SAML 2.0 configuration in the federation system. ## Guides * [**Set up a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection * [**SAML examples**](/docs/eid-hub/saml-2-0/saml-examples): Take a look at some SAML examples * [**Requested Attributes**](/docs/eid-hub/saml-2-0/saml-requested-attributes): Learn about SAML Requested Attributes * [**Level of Assurance contracts**](/docs/eid-hub/saml-2-0/saml-loa-contracts): Learn about LoA contracts and how to set them up ## External references - [SAML 2.0 OASIS specification - Technical overview](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#4.SAML%20Architecture|outline) - [SAML 2.0 OASIS specification - Metadata](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf) - [SAML 2.0 OASIS specification - Assertions and protocols](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) --- ## SAML examples ## AuthnRequest To initiate an authentication process, you send an `AuthnRequest` to Signicat. #### AuthnRequest basic example This example contains a basic SAML `AuthnRequest`. You can always add additional information in the request, but the bare minimum request can look like: ```xml ENTITY_ID XML_SIGNATURE ``` #### AuthnRequest example with language The following example shows how to specify the language as an attribute: ```xml {15-18} ENTITY_ID XML_SIGNATURE no ``` #### AuthnRequest example REDIRECT binding with prefilled attributes ```xml ENTITY_ID ... subject@example.com 1234567890 ``` #### AuthnRequest with IdP scoping [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx?protocol=saml) allows you to define which eIDs to make available for authentication to your users. To use IdP scoping with SAML 2.0, specify the eIDs in the `ProviderID` of the `IDPEntry` field, as shown below: ```xml {13} ENTITY_ID XML_SIGNATURE ``` To learn more about this feature, see the [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx?protocol=saml) documentation. #### AuthnRequest with RequestedAuthnContext and with REDIRECT binding ```xml ENTITY_ID urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport ``` ## AuthnResponse At the end of an authentication flow, the identity provider sends a SAML `AuthnResponse` to the service provider. In this case, Signicat sends you an `AuthnResponse` at the end of an end-user authentication flow. If the end-user authentication is successful, the response contains the `Assertion` with the `NameID` and attributes of the end-user. #### AuthnResponse example with DigiD Example of a SAML response after end-user login with DigiD: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... n8ek7xaPjR6XOGseV-NI9MJvLH6Zf2ciWC0gSEuLo5A= ENTITY_ID 900234854 NL PERSON urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport https://was-preprod1.digid.nl/saml/idp/metadata ``` #### AuthnResponse example with eHerkenning Example `AuthnResponse` after end-user login with eHerkenning: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE https://*YOUR_SIGNICAT_DOMAIN*/auth/saml XML_SIGNATURE k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y= ENTITY_ID Gerarda Josephina Kierkegaard Gerarda Josephina Kierkegaard email@example.com 03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4 24444001 819935177 urn:etoegang:DV:00000003244440010000:services:9121 cf1c1457-cc97-4b47-a324-25d1a97db3cb 24444002 Signicat Intermediary urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:00000003244440010000:entities:9713 ``` ## Learn more * [**Set up a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection * [**Requested Attributes**](/docs/eid-hub/saml-2-0/saml-requested-attributes): Learn about SAML Requested Attributes --- ## Level of Assurance contracts A Level of Assurance (LoA) contract is a set of mappings between the levels of assurance as defined in the eID's documentation (or protocol specifications) and some relative values (levels 1, 2, 2+, 3 and 4). For example, for SAML, `urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport` is mapped to level 2. ## Create a Level of Assurance contract To create a Level of Assurance contract: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Levels of Assurance**](https://dashboard.signicat.com/bca/loa-contracts). 2. Select **Add new** to create a new LoA contract. 3. In the **Name** field, enter a name for your set of mappings. 4. Under **Level of Assurance mapping**, enter the name of the level of assurance as defined for the eID (or protocol) you want to configure. Then, select the level of assurance you want to map it to. To map any additional level of assurance, select **Add more**. 5. Select **Save**. You can view an example of a mapping for eHerkenning: Example of a LoA mapping ## Learn more * [**Set up a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection * [**Add eID**](/identity-methods/): Continue to the eID setup to complete your initial configuration --- ## Set up SAML To set up a connection using SAML 2.0, you need to exchange metadata with Signicat. This process, known as _trust establishment_, allows the two parties to express trust for each other. The metadata also describes the type and format of the SAML 2.0 request and response. You can choose how to establish trust in the SAML 2.0 configuration in the Signicat Dashboard. You have the option to either self-host or upload the metadata in the Dashboard. On this page, you'll find instructions to set up SAML 2.0 in the Dashboard. You'll learn how to share or create the metadata and prepare yourself to connect to eIDs through the Signicat eID and Wallet Hub. You can also watch a video that shows how to set up SAML 2.0 in the [Tutorial videos](#tutorial-video) section. :::tip New customers If you are new to Signicat, learn more in the [Get started with Signicat](/docs/) page. ::: ## SAML metadata In SAML2.0, the service provider (SP) and the identity provider (IdP) establish connections by exchanging metadata with each other. The format of the metadata should follow the [SAML 2.0 OASIS specification](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf). ### Examples of metadata Below, you can find examples of metadata files configured with the POST or ARTIFACT bindings: ```xml XML_SIGNATURE KEY_NAME X509_CERTIFICATE ORG_NAME ORG_DISPLAY_NAME ORG_URL ``` ```xml XML_SIGNATURE KEY_NAME X509_CERTIFICATE ORG_NAME ORG_DISPLAY_NAME ORG_URL ``` ## How to exchange metadata To set up a secure connection over SAML 2.0 with Signicat eID and Wallet Hub, you have to provide us with a metadata file. You can choose between the following two ways: - [**URL configuration**](#add-url-configuration) (dynamic): You host and maintain the metadata file on your server. You generate the metadata file on your own, make it available at an endpoint and share the URL with us. Signicat fetches the metadata dynamically. When you want to update the metadata with new certificates, you only need to update the metadata on your server side. - [**Form configuration**](#add-form-configuration) (static): You upload or create a metadata in the Signicat Dashboard. You can either generate the file and upload it to the Dashboard or fill in a form in the Dashboard and have Signicat generate the metadata file for you. To update your metadata file with new certificates, you must re-upload the file manually on the Dashboard. The metadata file is stored inside Signicat's infrastructure. :::tip If you don't have a SAML 2.0 metadata file If you are not able to create a metadata file, you can fill in a form in the Dashboard to provide information about the connection. We use this information to automatically build a metadata file for you. ::: ### Add URL configuration The advantage with a URL configuration is that metadata exchange is dynamic. This means that your metadata and certificates are always up to date and are automatically updated whenever they change. This is because Signicat fetches the URL you provide periodically to ensure that we always use the latest version of your metadata. To establish a SAML connection with a **URL configuration** for your metadata, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp/) and select **+ Add new**. 2. Choose the **URL** configuration. 3. Fill in the following fields in the **Standard** tab: :::CustomTable{columnWidths="25% 25% 50%"} | Field name | Required | Description | | :---------------------- | :------- | :--------------------------------------------- | | Name | Yes | The name for your connection. | | Application URL | No | The URL of your application. | | Metadata URL | Yes | The web address where you host the metadata. | | Select a LoA contract | Yes | The Level of Assurance. Select the mapping between levels of assurance to apply to this configuration. See the [Level of Assurance contracts](/docs/eid-hub/saml-2-0/saml-loa-contracts.mdx) documentation. | ::: :::note Metadata URL verification If your Metadata URL appears unsafe, Signicat Support needs to verify the source. If your connection requires additional verification, click the **creating a support ticket** link in the notice banner to request verification and save your changes. Note that your connection will remain in a **Pending** state, until Signicat Support has verified your domain. ::: 4. To configure the **Advanced** tab, see the [Advanced URL configuration fields](#advanced-url-configuration-fields) section below. 5. Select **Add** to save the configuration. :::tip Get Signicat's metadata To view Signicat's metadata (XML file), select the **Get Signicat's metadata** button. Then, you can copy the file and store it in your application. Alternatively, you may configure your application to query the URL and load the metadata dynamically. ::: #### Connection status After saving your SAML 2.0 connection with URL configuration, you can track its status on the SAML 2.0 overview page. You may encounter the following statuses: - **Active**: The domain is trusted, and the metadata was successfully downloaded and parsed. Your SAML connection is fully operational. - **Inactive**: The connection has been manually deactivated. You can re-activate it at any time. - **Invalid**: The domain is trusted, but the system could not download or parse the metadata file correctly. This often happens due to a broken URL, a temporary network issue, or a corrupted XML file. :::tip Refresh the metadata To check whether your metadata file is valid, open your connection details and click **Refresh metadata** to manually retry fetching the file. If the issue persists, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: - **Pending**: Your connection is saved, but the root domain has not been verified yet. The system will not attempt to fetch metadata until Signicat Support approves your ticket. #### Advanced URL configuration fields :::CustomTable{columnWidths="25% 75%"} | Advanced field name | Description | | :------------------------------------------------------ | :----------------------------------------------- | | Want root signed even if the assertions are also signed | We recommend to always sign the root. If your application cannot handle multiple signatures, you may opt to disable signing of the root when signing the assertions. | | Use a transient format for the NameID | If you only want a transient "NameID", tick this box. | | Include the SAML Assertion of the IdentityProvider if available | If you use a SAML 2.0-based eID, you may opt to receive the original SAML 2.0 assertion from the eID. | | Encrypt assertion | If you want to receive an `EncryptedAssertion` instead of an `Assertion` for added security, select this option. Note that some eIDs require you to receive an `EncryptedAssertion`. You can select which algorithm to use for key and data encryption: _Data Encryption Algorithm_: The algorithm to use for data encryption. Default is [http://www.w3.org/2009/xmlenc11#aes128-gcm](http://www.w3.org/2009/xmlenc11#aes128-gcm). _Key Encryption Algorithm_: The algorithm to use for key encryption. Default is [http://www.w3.org/2009/xmlenc11#rsa-oaep](http://www.w3.org/2009/xmlenc11#rsa-oaep). If your application cannot work with these algorithms, you may select another algorithm from the dropdown menus. Our implementation of Encrypted Assertion is based on the SAML specification [https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) and the XML encryption specification [https://www.w3.org/TR/xmlenc-core1/](https://www.w3.org/TR/xmlenc-core1/). | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Select default eID rule | Select which default eID rule to use. To add eID rules in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/). | | Response attribute mappings | You can create mappings to customise the name of the attributes you receive in the response body. You can define none or many name-to-name mappings. | ::: #### Cache duration You can control the maximum length of time Signicat caches the metadata retrieved from the URL configuration by setting the `cacheDuration` in the metadata file, as specified in the [OASIS SAML 2.0 documentation](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf). The default `cacheDuration` of the metadata is set to 4 hours. This means that, if you update the metadata, it could take up to 4 hours before Signicat uses the new metadata. The highest value supported is 4 hours and the lowest value supported is 5 minutes. That means that, in case a `cacheDuration` larger than 4 hours is specified, it will refresh every 4 hours. Likewise, if a duration smaller than 5 minutes is specified, it will refresh every 5 minutes. On the `EntityDescriptor` you can add an (optional) attribute `cacheDuration`: ```xml ``` The duration should be formatted as described [here](https://www.w3schools.com/xml/schema_dtypes_date.asp). For example, to set the metadata `cacheDuration` to 30 minutes, add the `cacheDuration="PT30M"` attribute to your metadata, as shown: ```xml ... ``` ### Add Form configuration Form configuration is an alternative way to create a SAML connection when you prefer to: - Upload your metadata file in the Signicat Dashboard, or - Generate a metadata file by providing information in a web form. :::tip Generate a metadata We recommend you generate a metadata with the web form when you are not able to create a metadata file in your application. ::: Once you have added your metadata, the file is stored safely in the Signicat Dashboard. Remember that you can always modify its configuration. #### How to add a metadata file To create a new SAML 2.0 connection with **Form configuration** for your metadata, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp) and select **+ Add new**. 2. Choose the **Form** configuration option. Now, follow the instructions to either upload or generate the metadata file in the following sections. #### Upload a metadata file To share your metadata file: 1. Upload a valid XML file in the **Upload service provider metadata** section. 2. Fill in the **Name** with the name for your connection. 3. Optional, you may need to further customise your configuration by filling in the **Standard** and **Advanced** tabs. For more details about the fields in the form, see the next section. Once you have uploaded your metadata and configured your connection, select **Add** to save the changes. :::tip Get Signicat's metadata To view Signicat's metadata (XML file), select the **Get Signicat's metadata** button. Then, you can copy the file and store it in your application. Alternatively, you may configure your application to query the URL and load the metadata dynamically. ::: #### Generate a metadata file To let Signicat generate a metadata file for you, fill in the fields in the Standard and Advanced tabs. These are the fields you can configure: **Standard** :::CustomTable{columnWidths="25% 75%"} | Field name | Description | | :---------------------- | :--------------------------------------------- | | Name\* | Name of the connection. | | Application URL | URL of the service provider application. | | Metadata URL\* | The web address where you host the metadata. | | Select a LoA contract\* | Select the mapping between levels of assurance that must apply to this configuration. See [Level of Assurance contracts](/docs/eid-hub/saml-2-0/saml-loa-contracts.mdx) for more information. | ::: \* Required fields are marked with an asterisk (\*). **Advanced configuration** :::CustomTable{columnWidths="25% 75%"} | Field name | Description | | :-------------------------------------------------------------- | :------------------------------------------------------| | Want assertions signed | If ticked, assertions will be signed. | | Want root signed even if the assertions are also signed | We recommend to always sign the root. If your application cannot handle multiple signatures, you may opt to disable signing of the root when signing the assertions. | | Use a transient format for the NameID | Tick this box if you only want a transient NameID. | | Include the SAML Assertion of the IdentityProvider if available | If the eIDs that you use are SAML 2.0-based, you may opt to receive the original SAML 2.0 assertion of the eID. | | Encrypt assertion | If you want to receive an `EncryptedAssertion` instead of an `Assertion` for added security, select this option. Note that some eIDs require you to receive an `EncryptedAssertion`. You can select which algorithm to use for key and data encryption: _Data Encryption Algorithm_: The algorithm to use for data encryption. Default is [http://www.w3.org/2009/xmlenc11#aes128-gcm](http://www.w3.org/2009/xmlenc11#aes128-gcm). _Key Encryption Algorithm_: The algorithm to use for key encryption. Default is [http://www.w3.org/2009/xmlenc11#rsa-oaep](http://www.w3.org/2009/xmlenc11#rsa-oaep). If your application cannot work with these algorithms, you may select another algorithm from the dropdown menus. Learn more about XML encryption at [https://www.w3.org/TR/xmlenc-core1/](https://www.w3.org/TR/xmlenc-core1/). | | Assertion consuming services\* | At least one assertion consuming service must be configured. Provide a location URL and a binding type (`REDIRECT`, `POST` or `ARTIFACT`). | | Single logout services | Enter the location URL and binding type (`REDIRECT`, `POST` or `ARTIFACT`) of any applicable single logout services. | | Artifact resolution services | Enter the location URL, binding type and index of any applicable artifact resolution services. | | Attribute consuming services | Enter name, index, description (optional) and at least one attribute | | Certificate\* | Upload all relevant certificates for the connection (at least one). Information about the certificates, such as issuer and expiration date, is displayed when they are uploaded. | | Client organisation | Enter organisation name, display name, and URL. | | Hosting party organisation | Provide organisation name, display name, and URL. | | Contact people | Provide details about the contact people in your organisation. In **Type of contact person**, specify whether they are part of support, a technical department, name, phone number, and more. | You can customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. | | Select attribute filter | Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Select default eID rule | Select which default eID rule to use. To add eID rules in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/). | ::: \* Required fields are marked with an asterisk (*). Once you have completed your configuration, select **Add** to save the changes. :::tip Get Signicat's metadata To view Signicat's metadata (XML file), select the **Get Signicat's metadata** button. Then, you can copy the file and store it in your application. Alternatively, you may configure your application to query the URL and load the metadata dynamically. ::: ## Tutorial video This video shows you how to configure a SAML 2.0 connection in the Signicat Dashboard. ## Learn more Explore the SAML 2.0 documentation to discover request examples and learn about advanced topics. * [**SAML examples**](/docs/eid-hub/saml-2-0/saml-examples): Take a look at some SAML examples * [**Requested Attributes**](/docs/eid-hub/saml-2-0/saml-requested-attributes): Learn about SAML Requested Attributes --- ## SAML Requested Attributes Requested Attributes allow you to specify the user information (attributes) that you ask Signicat to include in the SAML assertion. You control the requested attributes by using the XML element `RequestedAttribute` which you can pass in your request in a few ways. The context of the `RequestedAttribute` element depends on the eID used. ## How it works You can define the `RequestedAttribute` element in a few different ways: 1. In the metadata file, by using `AttributeConsumingService`. 2. In the request, by using a SAML protocol extension in the `AuthnRequest`. 3. In the Signicat Dashboard, by configuring the attributes in the **Products** > **eID and Wallet Hub** > **Advanced** > [**eID Rules**](https://dashboard.signicat.com/bca/eid-rules/) (more information will follow soon). Below, you find more details and examples for the different mechanisms. ## AttributeConsumingService When you send an authentication request, Signicat looks up the `AttributeConsumingService` in the metadata file and returns the attributes corresponding to the `RequestedAttribute` elements, as defined in the metadata. Example of `AttributeConsumingService` with `index="1"` in a metadata file: ```xml {5,6} Example Service ``` :::note Note The `isRequired` attribute is not supported and will be ignored. ::: To use the `RequestedAttribute` defined in the `AttributeConsumingService` of your metadata file, you either pass the `AttributeConsumingServiceIndex` in the `AuthnRequest` or configure a default service, as explained below. ### AttributeConsumingServiceIndex with AuthnRequest To use a specific service, you include the index value in the `AttributeConsumingServiceIndex` element in your authentication request. ```xml ``` Using the example above, the SAML response will return the user attributes as specified in the `AttributeConsumingService` element with `index="1"` of the metadata file. ### Using a default AttributeConsumingService Alternatively, you can configure a default service in the metadata. This way, Signicat returns the attributes of the default `AttributeConsumingService` when no `AttributeConsumingServiceIndex` is passed in the `AuthnRequest`. You can configure a default service in two ways: - Include `isDefault="true"` in the `AttributeConsumingService` element of your metadata file: ```xml ``` - Add a default service in the **Advanced** tab in the Signicat Dashboard. To do this: 1. Navigate to **Products** > **eID and Wallet Hub** > [**SAML 2.0**](https://dashboard.signicat.com/bca/sp) and select your connection. 2. In the **Advanced** tab, select **+ Add new** next to **Attribute consuming services**. 3. Configure the following fields: - Enter a **Name** for the default service. - Enter the **Index** of the service. The index must match a value in the metadata. - Optional. Enter a **Description**. - Toggle the **Default** button. - Add the user attributes you wish to receive by default. How to add a default attribute consuming service ## RequestedAttributes in AuthnRequest You can specify the sets of user attributes on individual requests by using the SAML 2.0 Protocol Extension for requesting attributes, as explained in the [official specification](https://docs.oasis-open.org/security/saml-protoc-req-attr-req/v1.0/saml-protoc-req-attr-req-v1.0.html). In your `AuthnRequest` you can define the attributes with the `RequestedAttributes` element. ```xml {4-6} User Administrator ``` :::note Note The `AttributeValue` element in `RequestedAttributes` is not supported. Therefore, 'User' and 'Administrator' in the example above will be ignored. ::: ### Additional parameters Apart from regular requested attributes, the `AuthnRequest` to Signicat may contain additional parameters. These allow you to specify advanced aspects of an authentication session like the language or the service to use. You can pass additional parameters in the `RequestedAttributes` under the `Extensions` object. Here you specify the string the `signicat:param:` as the value of the `Name` field in the `RequestedAttribute` element. If the additional parameter requires you to provide a value, you can pass the value as a string in the `AttributeValue` element. #### Language For example, you can specify the language by using the `signicat:param:language` parameter, as shown in the example below: ```xml {4,10} fi ``` ### Prefilled information When you already know some information about the end-user and you want to display it on the authentication page, you can send the prefilled data in the `RequestedAttribute`. You can pass prefilled information in your request by using the `signicat:prefilled:parametername` format. Signicat supports the following attributes to prefill information in your SAML 2.0 request: :::CustomTable{columnWidths="25% 75%"} | Attribute | Description | |:----------|:------------| | `signicat:prefilled:nin` | National Identification Number (NIN). | | `signicat:prefilled:mobile` | Mobile number. | | `signicat:prefilled:dateOfBirth` | Date of birth. | | `signicat:prefilled:email` | Email address. | | `signicat:prefilled:username` | Username. | | `signicat:prefilled:deviceId` | Device ID. | | `signicat:prefilled:firstName` | First name. | | `signicat:prefilled:lastName` | Last name. | | `signicat:prefilled:bankAccountNumber` | Bank account number. | | `signicat:prefilled:organisation` | Organisation name or identifier. | ::: Note that an eID might support only a subset of attributes. #### Example The following example shows how to prefill information about email address (`signicat:prefilled:email`) and mobile number (`signicat:prefilled:mobile`): ```xml ... subject@test.com 1234567890 ``` ### Provider scoping Certain eIDs are comprised of a network of identity providers (or issuers), such as banks, that collectively offer authentication to their customers. You may want to offer your end-users only a limited number of these providers when the end-users authenticate with a specific eID. To learn more about this feature and see examples for SAML, see the [Provider scoping](/docs/eid-hub/concepts/idp-scoping/?protocol=saml#provider-scoping) documentation. ## Learn more * [**Set up a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection * [**SAML examples**](/docs/eid-hub/saml-2-0/saml-examples): Take a look at some SAML examples --- ## Information for Enterprise and Express customers We support our existing Enterprise and Express Electronic Signing solutions on our new platform. If you are a new customer or have recently migrated to our new platform, see our guide on [setting up an API integration](#set-up-an-api-integration) below. :::warning Important **If you are an existing customer but have not yet migrated to our new platform**, please contact Signicat to confirm the correct API for your use case before beginning any integration work. Once you have confirmation, you can find the documentation to use with your established integration here: [**Enterprise**](https://developer.signicat.com/cs/enterprise/docs/electronic-signatures/)   [**Express**](https://developer.signicat.com/cs/express/docs/signature/)   [**Dokobit**](https://www.dokobit.com/developers) ::: ## Set up an API integration If you are a new customer or have recently migrated to our new platform, you can now use our existing Enterprise and Express Electronic Signing solutions on our new platform. Setting up an API integration is the most flexible way of testing our signature solutions. You can use your preferred IDE, Framework, Postman, etc. using credentials provided by Signicat. :::tip Before you start the integration Before you set up an API integration, we recommend that you familiarise yourself with the [OpenAPI reference documentation](#api-reference) to learn about available endpoints and their properties. ::: ## Prerequisites Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **Signature API** for your API client. ::: ## Differences between our old and new platforms Our new platform introduces new endpoints for our established products: | API | new API URL | old API URL | | :--- |:--- |:--- | | Enterprise Sign API | `https://api.signicat.com/enterprise/sign` | `https://id.signicat.com/sign` | | Express Signature API | `https://api.signicat.com/express/sign` | `https://api.signicat.io/signature` | | Enterprise SOAP web services gateway | `https://api.signicat.com/enterprise/ws/` | `https://id.signicat.com/ws` | For more information on differences between our old and new platforms, take a look at our [migration guides](#migration-guides), which provide an overview of the changes. :::warning Important Our Enterprise SOAP web services are available to existing customers only. If you are working on a new integration or are planning to upgrade from an older version of our DocumentService, PackagingService or ArchiveService SOAP APIs, we strongly recommend that you use [our RESTful Sign API](/apis/electronic-signing/enterprise/) instead. ::: ## Guides ### Quick start guides See our quick start guides for our Enterprise and Express APIs. * [**Enterprise Sign API guide**](https://developer.signicat.com/cs/enterprise/apis/sign/sign-api/#using-the-api): Learn more about available operations and see code examples * [**Express Signature API guide**](https://developer.signicat.com/cs/express/docs/signature/guides/quick-start/): Learn more about available operations and see code examples * [**Enterprise DocumentService v3 guide**](https://developer.signicat.com/cs/enterprise/docs/electronic-signatures/guides/get-started/2-learn.html#using-documentservice-soap): Learn more about available operations and see code examples * [**Enterprise PackagingService v4 guide**](https://developer.signicat.com/cs/enterprise/docs/electronic-signatures/guides/get-started/2-learn.html#using-packagingservice-soap): Learn more about available operations and see code examples * [**Enterprise ArchiveService v3 guide**](https://developer.signicat.com/cs/enterprise/docs/electronic-signatures/guides/get-started/2-learn.html#using-archiveservice-soap): Learn more about available operations and see code examples ### Migration guides For more information on differences between our old and new platforms, take a look at our migration guides, which provide an overview of the changes. * [**Enterprise Electronic Signing migration guide**](/docs/electronic-signing/enterprise-express/migration-guides/enterprise-sign-migration): Migrate to our new Digital Trust Platform * [**Express Electronic Signing migration guide**](/docs/electronic-signing/enterprise-express/migration-guides/express-sign-migration): Migrate to our new Digital Trust Platform * [**Sign API v2 terminology differences to our Enterprise signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-enterprise) * [**Sign API v2 terminology differences to our Express signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-express) ## API reference Explore our API reference documentation to look up all API endpoints and properties as well as view sample requests and responses. * [**Enterprise Sign API reference**](/apis/electronic-signing/enterprise/) * [**Express Signature API reference**](/apis/electronic-signing/express/) * [**Enterprise DocumentService v3 API reference**](https://developer.signicat.com/cs/enterprise/apis/sign/documentservice/v3.html) * [**Enterprise PackagingService v4 API reference**](https://developer.signicat.com/cs/enterprise/apis/sign/packaging-service/v4.html) * [**Enterprise ArchiveService v3 API reference**](https://developer.signicat.com/cs/enterprise/apis/sign/archiveservice/v3.html) --- ## Enterprise migration guide We now support our existing Enterprise Electronic Signing solutions on our new Digital Trust Platform (DTP). If you are a new customer or have recently migrated to our new platform, the following guide will provide an overview of the changes. ## Enterprise Sign API ### URL and API authorisation See our guide on [setting up an API integration](/docs/electronic-signing/enterprise-express/#set-up-an-api-integration). Our new platform introduces new endpoints for our established products: :::CustomTable | API | New API URL | Old API URL | | :-------------------|:----------------------------------------------|:--------------| | Enterprise Sign API | `https://api.signicat.com/enterprise/sign` | `https://id.signicat.com/sign` | ::: ### Error responses Our platform will return error responses in the [Problem Detail RFC format](https://datatracker.ietf.org/doc/html/rfc7807) for all errors that occur before the request is forwarded. The potential errors that can arise before the request is forwarded are: - 4xx errors - 5xx errors - Token validation errors - Errors relating to validation of the request URL path or parameters - Errors relating to general validation of correct HTTP verb, URL parameters, payloads, not empty payload if required - Errors relating to dependencies in our new platform, such as global configuration If the response `Content-Type` is text or JSON, all URLs containing the full URL of the existing (Enterprise) API will get replaced with a `https://api.signicat.com` URL with the `enterprise` prefix path. ## Enterprise SOAP web services :::warning Important Our Enterprise SOAP web services are available to existing customers only. If you are working on a new integration or are planning to upgrade from an older version of our DocumentService, PackagingService or ArchiveService SOAP APIs, we strongly recommend that you use [our RESTful Sign API](/apis/electronic-signing/enterprise/) instead. ::: ### URL and API authorisation See our guide on [setting up an API integration](/docs/electronic-signing/enterprise-express/#set-up-an-api-integration). Our new platform introduces new endpoints for our established products: :::CustomTable | API | New API URL | Old API URL | | :-----------------------------------|:----------------------------------------------|:--------------------| | Enterprise SOAP web services gateway | `https://api.signicat.com/enterprise/ws/` | `https://id.signicat.com/ws/` | ::: MTLS client certificates are now replaced with a JWT authorisation header using the Bearer scheme. Note that any errors as a result of JWT token validation will produce new error messages, but will retain the SOAP error format. #### Obtain an access token To obtain your access token, you use the same process as you would for other REST services on our new platform. :::info Want to learn more? To learn how to do this, see the [Obtain an access token](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx#4-obtain-an-access-token) section in the **Connect to Signicat APIs** quick start guide. ::: #### Using the access token To use your access token, add it to the SOAP request header in the same way you would for a REST request header. :::info Want to learn more? To learn how use access tokens in REST request headers, see the [Make an API request](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx#5-make-an-api-request) section in the **Connect to Signicat APIs** quick start guide. ::: Refer to your client library documentation for information on how to set the header in your specific case. For example, if you use the Java CXF library, you can set the header through the `requestContext` of `BindingProvider`. :::tip Note You need to include a username and password in the payload. ::: ### Uploading documents If you are an existing customer using [DocumentService v3](https://developer.signicat.com/cs/enterprise/apis/sign/documentservice/v3.html) and [PackagingService v4](https://developer.signicat.com/cs/enterprise/apis/sign/packaging-service/v4.html) and have recently migrated to our new platform, documents are now uploaded to our Sign API's built-in Session Data Storage (SDS) by using the [documents endpoint](pathname:///apis/electronic-signing/enterprise/#tag/document/operation/uploadFileToSds). For more information, see our guide on [setting up an API integration](/docs/electronic-signing/enterprise-express/#set-up-an-api-integration). ### Retrieving documents To retrieve documents, use the same endpoints that are established in our REST Sign API: - For documents in Session Data Storage (SDS), use the [documents endpoint](pathname:///apis/electronic-signing/enterprise/#tag/document). - For archive documents, use the [archive-documents endpoint](pathname:///apis/electronic-signing/enterprise/#tag/archive-document). ### Error responses Our platform will return error responses in the [Problem Detail RFC format](https://datatracker.ietf.org/doc/html/rfc7807) for all errors that occur before the request is forwarded. The potential errors that can arise before the request is forwarded are: - 4xx errors - 5xx errors - Token validation errors - Errors relating to validation of the request URL path or parameters - Errors relating to general validation of correct HTTP verb, URL parameters, payloads, not empty payload if required - Errors relating to dependencies in our new platform, such as global configuration If the response `Content-Type` is text or JSON, all URLs containing the full URL of the existing (Enterprise) API will get replaced with a `https://api.signicat.com` URL with the `enterprise` prefix path. --- ## Express migration guide We now support our existing Express Electronic Signing solutions on our new Digital Trust Platform (DTP). If you are a new customer or have recently migrated to our new platform, the following guide will provide an overview of the changes. ## URL and API authorisation See our guide on [setting up an API integration](/docs/electronic-signing/enterprise-express/#set-up-an-api-integration). Our new platform introduces new endpoints for our established products: :::CustomTable | API | new API URL | old API URL | | :---------------------|:-------------------------------------------|:------------------------------------| | Express Signature API | `https://api.signicat.com/express/sign` | `https://api.signicat.io/signature` | ::: ## Custom domains Domain setup is now self-serviceable through our Dashboard. See [our documentation on adding a domain](/docs/dashboard/organisation-management/domains/) for details. ## Signature events Events such as webhooks are now self-serviceable through our Dashboard. See [our new Events and webhooks documentation](/docs/dashboard/settings/events.mdx) for information on setting up and managing events. Note that the names and content of the events have changed in our new platform. Additionally, events in our new platform contain no personally identifiable information, only IDs. The table below shows the differences in event names between our old and new platforms. :::CustomTable{columnWidths="50% 50%"} | Old event name | New event name | | ----------------------------------------| ----------------------------- | | `document_before_deleted` | `order.tobedeleted` | | `document_canceled` | `order.canceled` | | `document_created` | `order.created` | | `document_deleted` | `order.deleted` | | `document_expired` | `order.expired` | | `document_email_opened` | `email.opened` | | `document_link_opened` | `session.started` | | `document_packaged` / `document_signed` | `order.completed` | | `document_partially_signed` | `recipient.completed` | | `document_read` | `session.document.presented`Note that the `id`property in the event will be the `documentId` from the API. The `documentId` property may be the `documentId` or the `attachmentId`. | The `id`property in the event will be the `documentId` from the API. The `documentId` property may be the `documentId` or the `attachmentId`. | ::: ## Communication (SMS / Email notifications) Notification settings are now self-serviceable through our Dashboard. See [our Communication service documentation](/docs/dashboard/branding/communication.mdx) for information on managing configurations for SMS messages and email. ## Validating redirect JWT tokens You can still follow our existing [Redirects guide](https://developer.signicat.com/cs/express/docs/signature/create-document.html#redirects) but we have noted in the guide that you will need to use the URL `https://api.signicat.com/express/sign/jwt/validate` in your [POST request in step 4](https://developer.signicat.com/cs/express/docs/signature/create-document.html#step-4-parse-and-validate-the-jwt-optional) to parse and validate the JWT if you are using our new platform. ## Enabling eIDs You or your onboarding manager will need to enable the eIDs you want to use in the Signicat Dashboard. To do this, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). ## Other changes - We now use our new [Authentication REST API](/docs/eid-hub/authentication-api/) for authentication-based signing. Therefore the naming of the attributes in the PAdES evidence package (JSON/XML files) have changed slightly. The same is true for the eID attributes included in the `documentSignature.attributes` in the [Signicat Signature API](/apis/electronic-signing/express/). - If you use our Secure Share service as an add-on, note that the user interface of the latest version of Secure Share will look different from our [old Secure Share service](https://developer.signicat.com/cs/express/docs/share/). --- ## Migration guides(Migration-guides) For more information on differences between our old and new platforms, take a look at our migration guides, which provide an overview of the changes. * [**Enterprise Electronic Signing migration guide**](/docs/electronic-signing/enterprise-express/migration-guides/enterprise-sign-migration): Migrate to our new Digital Trust Platform * [**Express Electronic Signing migration guide**](/docs/electronic-signing/enterprise-express/migration-guides/express-sign-migration): Migrate to our new Digital Trust Platform * [**Sign API v2 terminology differences to our Enterprise signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-enterprise) * [**Sign API v2 terminology differences to our Express signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-express) --- ## Electronic Signing Signicat's Electronic Signing solutions allow you to digitalise business processes by applying electronic signatures on documents such as contracts and loan agreements. The advantage of our Electronic Signing solutions is the ability to securely identify the user according to EU regulations - a key component for providing compliant electronic signatures. Signicat's electronic signing solutions are comprised of two services: * [**Sign API v2**](/docs/electronic-signing/sign-api-v2/): Electronic signatures for both small to medium sized businesses and those within regulated industries * [**Enterprise and Express**](/docs/electronic-signing/enterprise-express/): Enterprise and Express electronic signing for existing customers ## Features We offer REST APIs using European identity providers (as well as SMS and Email OTP) for creating electronic signatures on contracts, declarations, forms and other documents. - OAuth2 for authentication - Customisable, responsive signing interface - Authentication-based signing or third-party (native) signing - Advanced and Qualified Electronic Signatures (AES and QES) as defined by the eIDAS European regulation - Signed documents in XAdES or PAdES format - Support for signer queues and workflows ## Use case examples Signicat's Electronic Signing solutions are built flexibly, to enable you to implement any use case that you might have. Here are some examples of how our different solutions are being used today: - Signing of PDF documents containing interactive forms - Signing of short text statements using Signed Statement - Headless signing of text elements with Consent Signature - Collecting of signatures on multiple documents at the same time - Signature forwarding/ approvals - Handwritten signatures - Sealing - Signature validation - Secure document sharing - Signicat Dashboard user management - Business-to-business (B2B) signing and sealing (Merchant signing) ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Sign API v2 terminology ## Collections and signing sessions Our Sign API v2 has the concepts of **document collections** and **signing sessions**. A collection can contain one or more signing sessions. - A **document collection** is a collection of documents that naturally belong together. - A **signing session** specifies the signer and the documents they are asked to sign, along with other details such as contact details, allowed signing methods, the resulting format (XAdES/PAdES), archiving preferences, subject validation details, 'auth before sign' settings and conditional redirect URLs based on the state of the signing session. :::note Note - Learn how to manage multiple documents and signing sessions with document collections in our [Document collections](/docs/electronic-signing/sign-api-v2/features/document-collections/) feature guide. - Learn more about our [Document collections](pathname:///apis/electronic-signing/sign-api-v2/#tag/Document-collections) and [Signing sessions](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions) endpoints in our API reference. ::: Collections and signing sessions ### Signing sessions spanning several different collections Signing sessions can include documents from several different collections. If you package a collection, it will only include the signed documents that belong to that collection, not documents from other collections signed in the same signing session. Signing sessions spanning several collections --- ## Core concepts Understand key terms and how they differ from our previous electronic signature APIs * [**Sign API v2 terminology**](/docs/electronic-signing/sign-api-v2/core-concepts/concepts/) * [**Terminology differences to our Enterprise signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-enterprise) * [**Terminology differences to our Express signing solution**](/docs/electronic-signing/sign-api-v2/core-concepts/terminology-differences-express) --- ## Terminology differences to our Enterprise signing solution ## Signing order **All collections and their associated signing sessions** in our Sign API v2 are the equivalent of a **signing order** in our Enterprise signing solution. Signing order ## Task A **signing session** in our Sign API v2 is the equivalent of a **task** in our Enterprise signing solution. Task ## User-centric session **Signing sessions spanning several different collections** in our Sign API v2 are the equivalent of a **user-centric session** in our Enterprise signing solution. User-centric session --- ## Terminology differences to our Express signing solution ## Documents and signers A **collection and its associated signing sessions** in our Sign API v2 are the equivalent of the **documents and signers** in our Express signing solution. Express terminology differences --- ## Error codes for Sign API v2 # Error codes When you make a request to Signicat's Sign API v2 and there is an error, you will receive a response with an error message that contains an error code. If you encounter an error and require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. The table below shows how to interpret some of the error codes that you might encounter when using the API. :::tip Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: :::CustomTable | Error code | Title | HTTP status | Description | |-------------------------------|-----------------------------------------------|---------------|---------------------------------------------------------------------------------------------------| | `document_password_protected` | `Document is password protected` | 400 | The uploaded document is password-protected and cannot be read. | | `document_encrypted` | `Document is encrypted` | 400 | The uploaded document is encrypted and cannot be read. | | `document_infected` | `Document is infected` | 400 | The uploaded document was flagged as containing a virus and was rejected for security reasons. | | `document_contains_javascript`| `Document contains JavaScript` | 400 | The uploaded document contains embedded JavaScript and was rejected for security reasons. | | `invalid_id_format` | `Supplied parameter was not in UUID format` | 400 | The provided parameter is not a valid UUID. | ::: --- ## Archive ## About this feature Our Sign API V2 offers an embedded archive feature that allows you to securely store signed documents. This feature ensures that all documents are preserved in compliance with legal requirements. ## Use cases - Archiving of signed documents - Setting of retention periods for archived documents :::tip Note - To manage archived documents, use our [Signicat Archive](/docs/signicat-archive/) solution. ::: ## Integration details ### Sending a document to the archive To have the result from the signing session automatically sent to the archive, specify this when you create the signing session. Add an `archive` object to your HTTP POST request to the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions/operation/createSigningSession) and include `sendSignatureResultsToArchive` and `retentionPeriod`. The `retentionPeriod` field is required. :::tip Note `retentionPeriod` must be an ISO 8601 duration string (for example `P1Y` for one year). ::: #### Request example The following is an example of an `archive` object within an HTTP POST request to the [Signing sessions endpoint: ```json { "archive": { "sendSignatureResultsToArchive": true, "retentionPeriod": "P1Y" }, "...": "other signing session fields" } ``` ### Archive confirmation and tracking When archiving completes, the service returns an `archiveId`. Receipt of an `archiveId` confirms that the signature result was archived successfully. :::warning Important You must retain the `archiveId` in your system. We strongly recommend storing the `archiveId` together with relevant signer identifiers or business references so you can trace which signer signed which document and retrieve the archived object later. ::: ### Managing archived documents Our Sign API v2 can send packaged results to an archive, but advanced archive operations are handled by our standalone Signicat Archive solution. See our [Signicat Archive](/docs/signicat-archive/) documentation for the API reference and endpoints. You can use our Signicat Archive API for: - Object submission - Object archiving - Tagging of archived objects - Searching for archived objects - Retrieval of archived objects - Updating of archived objects - Object reports - Object audit logs via API - Retention management --- ## Document collections ## About this feature Our Sign API V2 introduces the concept of the **document collection**, which provides a flexible way to group and manage documents throughout the signing process, with automatic packaging capabilities upon completion. ## Use cases - **Multi-phase signing processes** where signers may be added incrementally. - **Flexible signing scenarios** where the complete signer list may not be known upfront. ## Technical benefits - **Scalable document management** through collection-based organisation - **Automated compliance** via merchant certificate sealing - **Workflow flexibility** during the active signing phase - **Asynchronous processing** for improved system performance - **Clear lifecycle management** with defined closure upon completion ## Core concepts ### Document collection structure - A document collection serves as a container that can hold one or more documents that naturally belong together. - Each document within a collection can be referenced by one or more signing sessions. - The relationship between signing sessions and documents follows a many-to-one pattern, where multiple signing sessions can reference a single document that belongs to a document collection. ### Automatic packaging and sealing functionality Document collections include the `packageTo` concept, which enables automatic packaging and sealing: - **Automatic packaging**: When all signing sessions referenced by documents in a document collection are completed, the system automatically packages them into a PAdES (PDF Advanced Electronic Signatures) format - **Merchant certificate sealing**: The packaged PAdES is sealed using a merchant certificate for authenticity and integrity - **Optional and asynchronous**: The `packageTo` field is optional and operates asynchronously, allowing for flexible workflow management ### Dynamic session management Document collections follow these rules during the signing lifecycle: - Pre-package flexibility: New signing sessions can be created and can reference new document collections until the packaging process has been completed. - Workflow continuity: This allows for dynamic addition of signers or documents during the active signing phase. - Collection closure: Once the document collection has been packaged, it becomes closed and no new signing sessions can be created that reference documents from that collection. ## Limitations ### Packaging configuration limitations Only one level of PAdES packaging is supported - either at the signing session level or at the document collection level, but not both. This means that you must not set the `packageTo` field on a *signing session* if it references documents from a *document collection* that has `packageTo` PAdES set. This conflict is difficult to validate upfront because document collections only own and manage *documents*, not the signing sessions themselves. A signing session may contain documents from different document collections with different `packageTo` configurations. It's therefore important to ensure proper coordination between signing session and document collection packaging settings. ### Future enhancements A planned enhancement will introduce functionality to **package individual PAdES results from signing sessions into a Signicat PAdES container**, where each signing session's PAdES (or Xades if `packageTo` is not set) will be included as an attachment within the final packaged document. --- ## Features and functionality You can learn about Sign API v2 features and functionality in our feature guides. * [**Archive**](/docs/electronic-signing/sign-api-v2/features/archive): Learn how to securely store signed documents in compliance with legal and regulatory requirements * [**Document collections**](/docs/electronic-signing/sign-api-v2/features/document-collections): Learn how to manage multiple documents and signing sessions with document collections * [**Merchant signing**](/docs/electronic-signing/sign-api-v2/features/merchant-signing): Learn how to implement business-to-business (B2B) signing with merchant certificates * [**Signature forwarding**](/docs/electronic-signing/sign-api-v2/features/signature-forwarding): Learn how to allow end-users to delegate signing sessions to others * [**Simple text signing**](/docs/electronic-signing/sign-api-v2/features/simple-text-signing): Learn how to implement simple text signing with Sign API v2 --- ## Merchant signing ## About this feature Merchant signing, also known as business-to-business (B2B) signing or sealing, allows you to sign documents using a merchant certificate from a selected vendor. This is useful for automated signing processes where a legal entity, rather than an individual person, is the signer. :::warning Limitation The only vendor currently available for merchant signing is **Norwegian BankID** (`NBID`). ::: ## Configuration and setup To use merchant signing, Signicat Support will need to set up the client configuration for the selected vendor for you. This process will differ slightly between vendors. For vendor-specific details and configuration, see the relevant documentation: * [**Norwegian BankID Merchant signing**](/identity-methods/nbid/integration-guide/sign-nbid/#merchant-signing): Vendor-specific merchant signing details ## Use cases - **Automated sealing**: Automatically sign outgoing documents (like invoices or contracts) with your company's merchant certificate to ensure authenticity and integrity. - **B2B signing**: Sign documents on behalf of your organisation in a B2B context. - **XML signing**: Sign XML messages for services like Løsøreregisteret (Brønnøysundregistrene) using the XAdES format. - **Mixed signing flows**: Combine merchant signing with end-user signing. For example, a document can first be signed by an individual and then sealed by the organisation. ## How it works Unlike the standard signing process in our Sign API v2, merchant signing does not use document collections or signing sessions. Instead, you make an API call to our [Merchant signing endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Merchant-signing/operation/merchantSign) that returns the signed document immediately. ### Integration steps The process for merchant signing consists of three steps: 1. **Upload the document**: Make an HTTP POST request with the document's binary data to the [Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documentsoperation/uploadDocument). This returns a `documentId`. 2. **Perform merchant signing**: Make an HTTP POST request to the [Merchant signing endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Merchant-signing/operation/merchantSign) with the `documentId` and the desired `vendor`. This returns a `documentResultId`. 3. **Download the result**: Make an HTTP GET request using the `documentResultId` to the [Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents/operation/getDocument) to download the signed document. :::tip Note Since both the original document and the signed result are not connected to a "parent" object (like a signing session), they are not stored long-term in our system. We recommend downloading the result immediately after signing. ::: ### Request example To perform merchant signing, make an HTTP POST request to the [Merchant signing endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Merchant-signing/operation/merchantSign): ```json { "vendor": "NBID", "toBeSignedDocuments": [ { "documentId": "d1234567-89ab-cdef-0123-456789abcdef", "mimetype": "application/pdf", "format": "PADES", "description": "Invoice #12345" } ] } ``` ### Response example The API returns an array of results, one for each document in the request: ```json [ { "documentId": "d1234567-89ab-cdef-0123-456789abcdef", "documentResultId": "0197d5cb-d683-7451-9b21-1a2da906b353" } ] ``` You can then use the `documentResultId` to download the signed document, as described in our [integration guide](/docs/electronic-signing/sign-api-v2/integration-guide/#7-download-the-signed-document). ### Signing already signed documents Merchant signing can be performed on documents that have already been signed, provided they meet certain criteria: - There is a strict validation of the certificate chain, and Signicat only supports a specific list of trust anchors. - Documents already signed through Signicat can be mixed with merchant signing. ### XAdES support for XML documents You can use the [Merchant signing endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Merchant-signing/operation/merchantSign) to sign XML messages using the XAdES format. This is particularly useful for Business-to-Business (B2B) services that require signed XML payloads, such as Løsøreregisteret (Brønnøysundregistrene). #### 1. Prepare the XML document Before uploading the document, you must prepare the base XML payload. Add an empty node as the last child of the root node to hold the signatures. This node can be named anything (for example, ``, as in the example below). It acts as a placeholder where the XAdES signature will be injected after the signing process is complete. ##### Example payload ```xml ... ``` #### 2. Upload the document Currently, our document storage service does not natively support XML document types. Therefore, when you upload the XML document to the Documents endpoint, you must set the `Content-Type` header to `text/plain`. #### 3. Request the merchant signature Once the document is uploaded and you have the `documentId`, you can request the signature by calling the Merchant signing endpoint. In the request body, specify the `format` as `XADES` and the `mimetype` as `text/xml`. ##### Example request ```json { "vendor": "NBID", "toBeSignedDocuments": [ { "documentId": "d1234567-89ab-cdef-0123-456789abcdef", "mimetype": "text/xml", "format": "XADES", "description": "Invoice #12345" } ] } ``` #### 4. Retrieve the signed document The response format for this request is identical to the default merchant signing response. When you retrieve the final signed document, the previously empty `` node from our example payload will now be populated with the generated `` data. ##### Example result document ```xml ... ... ``` :::tip Note You can find provider-specific Sign API v2 integration guides in our ID methods documentation: - [Norwegian BankID](/identity-methods/nbid/integration-guide/sign-nbid.mdx) - [Swedish BankID](/identity-methods/sbid/integration-guide/sign-sbid.mdx) ::: --- ## Signature forwarding ## About this feature Signature forwarding allows end-users to send a signing session to another person and nominate that person as a signer. This feature is particularly useful in business-to-business (B2B) contexts where the initial recipient of a signing request may not be the authorised signer, or where multiple individuals need to be involved in a signing process sequentially. When a session is forwarded, a new, independent signing session is created for the recipient and linked back to the original. This new child session is a copy of the parent session (including documents, UI and redirect settings, authentication setup and archiving configuration), with the new recipient set as its signer. This parent-child relationship is tracked via the `session.forwarding.parentSessionId` and `session.forwarding.childSessionIds` properties, allowing each session to trace which session it was forwarded from and which session it was forwarded to. ## Use cases - **Business-to-business (B2B)**: A company representative receives a contract but does not have the legal authority to sign it, so they forward it to an authorised person within their organisation. ## How it works When signature forwarding is enabled, the end-user will see a **Forward** option in the **More actions** dropdown menu at the top right of the signing interface. A screenshot of the dropdown menu in the signing interface, showing the Forward option. Selecting this opens a form where it's possible to delegate the signing responsibility. The original sender will be informed of this action. A screenshot of the Forward documents form, with fields for the recipient's name, email, a message and the sender's name. ### Integration steps The process for signature forwarding consists of three steps: 1. **Initiating a forward**: The original recipient fills out the form with the following details: 1. **Name**: The name of the recipient of the forwarded session. 2. **Email**: The email address of the recipient of the forwarded session. 3. **Message**: An optional custom message to be included in the notification email. 4. **Sender**: The name of the sender of the forwarded session 2. **Session tracking**: Submitting the form creates a new child signing session. The original parent session is updated with a `childSessionIds` property containing the ID of the new session. The new child session will have a `parentSessionId` property, linking it back to the original. 3. **Preventing further forwarding**: The new child session is created with its own forwarding capability disabled to prevent daisy-chaining. Once the form is submitted, the new child session is initially created in a blocked state and becomes active once fully set up. This triggers the email notification containing the custom message and a link to review and sign the document to the recipient of the forwarded session. A screenshot of the email notification sent to the new recipient, inviting them to sign the forwarded document collection. ### Configuration and setup :::tip Note Using this feature requires the `SIGN-FORWARD` product entitlement to be enabled on your account. ::: When you create a signing session, add the relevant parameters to the request body in your HTTP POST request to the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions/operation/createSigningSession). To configure signature forwarding, include the `forwarding` object in your `createSigningSession` request with the following properties: - **`flow`**: Set this to `FORWARD_AND_CONTINUE` to enable forwarding. The default value is `NONE`, which disables the feature. - **`senderAddress`** (optional): The email address from which forwarding notifications are sent. This requires a custom domain configured for your account; otherwise, notifications are sent from the default `noreply@signicat` address. ### Request example The following is an example of a `createSigningSession` request body to initiate the parent session (session A) with forwarding enabled: ```json {17-19} { "title": "Le doc", "documents": [ { "documentCollectionId": "{{collectionId}}", "action": "SIGN", "documentId": "{{documentId}}" } ], "senderDisplayName": "Some sender", "externalReference": "abc-123", "signingSetup": [ { "signingFlow": "AUTHENTICATION_BASED" } ], "forwarding": { "flow": "FORWARD_AND_CONTINUE" } } ``` ### Response example before forwarding A successful request returns a `201 Created` status code and the initial `SigningSession` object for the parent session (session A). At this stage, the nested `forwarding` block confirms that the feature is enabled but shows no active delegations: * **`flow`**: Confirms that forwarding is active (`FORWARD_AND_CONTINUE`). * **`childSessionIds`**: An empty list (`[]`) because the end-user has not yet forwarded their signing invitation. ```json {49-52} { "id": "019fd706-2377-7ef5-bf60-3e656986dc23", "signatureUrl": "https://sign-customer-local.sandbox.signicat.dev/sign?sessionId=019fd706-2377-7ef5-bf60-3e656986dc23", "title": "Le doc", "dueDate": "2026-09-05T12:22:11.333920635Z", "documents": [ { "documentCollectionId": "019fd705-bd8e-7cf9-973d-2c9c778dc094", "action": "SIGN", "documentId": "019fd705-af77-7b6e-8562-97dbc4dd3a1f" } ], "lifecycle": { "state": "READY", "stateIsFinal": false }, "senderDisplayName": "Some sender", "output": { "signatures": [], "packages": [], "userInfo": { "extra": {} }, "seals": [] }, "externalReference": "abc-123", "signingSetup": [ { "identityProviders": [], "signingFlow": "AUTHENTICATION_BASED", "additionalParameters": {}, "requestedAttributes": [] } ], "subsequentTo": [], "packageTo": [], "sealTo": [], "archive": { "sendSignatureResultsToArchive": false, "sendPackagingResultToArchive": false, "archiveTags": [] }, "ui": { "hideWelcomeScreen": false, "minimalTextMode": false }, "intentionText": {}, "usageTags": [], "forwarding": { "flow": "FORWARD_AND_CONTINUE", "childSessionIds": [] } } ``` ### Response example after forwarding Once the end-user delegates the signing, retrieving the parent session (session A) via a `GET` request shows the newly established link to the delegated session. The key change occurs within the `forwarding` block: * **`childSessionIds`**: Now contains the server-generated ID of the child session (session B). ```json {50-55} { "id": "019fd706-2377-7ef5-bf60-3e656986dc23", "signatureUrl": "https://sign-customer-local.sandbox.signicat.dev/sign?sessionId=019fd706-2377-7ef5-bf60-3e656986dc23", "title": "Le doc", "dueDate": "2026-09-05T12:22:11.333921Z", "documents": [ { "documentCollectionId": "019fd705-bd8e-7cf9-973d-2c9c778dc094", "action": "SIGN", "documentId": "019fd705-af77-7b6e-8562-97dbc4dd3a1f" } ], "lifecycle": { "state": "READY", "stateIsFinal": false }, "senderDisplayName": "Some sender", "output": { "signatures": [], "packages": [], "userInfo": { "extra": {} }, "seals": [] }, "externalReference": "abc-123", "signingSetup": [ { "identityProviders": [], "signingFlow": "AUTHENTICATION_BASED", "additionalParameters": {}, "requestedAttributes": [] } ], "subsequentTo": [], "packageTo": [], "sealTo": [], "archive": { "sendSignatureResultsToArchive": false, "sendPackagingResultToArchive": false, "archiveTags": [] }, "ui": { "hideWelcomeScreen": false, "minimalTextMode": false }, "intentionText": {}, "notifications": [], "usageTags": [], "forwarding": { "flow": "FORWARD_AND_CONTINUE", "childSessionIds": [ "019fd70d-0ca0-7795-b94a-bac33f18c1be" ] } } ``` ### Response example for the forwarded session When you retrieve the newly created child session (session B) via a `GET` request, the payload contains the configuration inherited from session A, along with new properties representing the new signer's context: * **`signer`**: Populated with the new recipient's details (such as the email address `"test.testerson@testcat.test"`). * **`notifications`**: Contains the `FORWARDING_NOTIFICATION` structure configured for emailing the new signer. * **`forwarding`**: The `flow` is set to `"NONE"` to prevent further forwarding (as chains are not allowed). The `parentSessionId` points back to the parent session (session A), creating a clear, two-way cryptographic link. ``` json {38-42,54-63,65-69} { "id": "019fd70d-0ca0-7795-b94a-bac33f18c1be", "signatureUrl": "https://sign-customer-local.sandbox.signicat.dev/sign?sessionId=019fd70d-0ca0-7795-b94a-bac33f18c1be", "title": "Le doc", "dueDate": "2026-09-05T12:22:11.333921Z", "documents": [ { "documentCollectionId": "019fd705-bd8e-7cf9-973d-2c9c778dc094", "action": "SIGN", "documentId": "019fd705-af77-7b6e-8562-97dbc4dd3a1f" } ], "lifecycle": { "state": "READY", "stateIsFinal": false }, "senderDisplayName": "Some sender", "output": { "signatures": [], "packages": [], "userInfo": { "extra": {} }, "seals": [] }, "externalReference": "abc-123", "signingSetup": [ { "identityProviders": [], "signingFlow": "AUTHENTICATION_BASED", "additionalParameters": {}, "requestedAttributes": [] } ], "subsequentTo": [], "packageTo": [], "sealTo": [], "signer": { "email": "test.testerson@testcat.test", "prefill": [], "validations": [], "restrictUse": [] }, "archive": { "sendSignatureResultsToArchive": false, "sendPackagingResultToArchive": false, "archiveTags": [] }, "ui": { "hideWelcomeScreen": false, "minimalTextMode": false }, "intentionText": {}, "notifications": [ { "category": "FORWARDING_NOTIFICATION", "communicationMethod": "EMAIL", "tags": [], "message": { "language": "en" } } ], "usageTags": [], "forwarding": { "flow": "NONE", "parentSessionId": "019fd706-2377-7ef5-bf60-3e656986dc23", "childSessionIds": [] } } ``` ## Limitations - A signing session can be forwarded a maximum of **5 times**. - A forwarded session cannot itself be forwarded (no chains). - The `forwarding` and `signer.validations` properties cannot be used together in the same session. - Forwarding is blocked if the session's document collections have hit their reference limit. - Notifications from the original session are not carried over to the new session. --- ## Simple text signing ## About this feature Simple text signing lets you capture a lightweight, binding confirmation from an end-user after they authenticate with an eID method. The signature is produced without a full document-based signing ceremony. Instead, the system records the authenticated end-user's identity together with the text they agreed to. ## How it works 1. You create a signing session specifying that the session uses simple text signing. 2. The end-user is redirected to authenticate with one of the supported eID methods. 3. Optional: Some values can be prefilled and shown to the end-user. 4. The end-user reviews the text you supplied in the session request. 5. The end-user confirms their consent. 6. The API returns a signed result object that includes the agreed text, signing metadata and identity information. ## Core API elements ### Create signing session request When you create a signing session, add the relevant parameters to the request body in your HTTP POST request to the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions). These parameters determine what the end-user sees and how the flow behaves. Example fields you can include: - Parameters that enable simple text signing - Optional prefill configuration - Optional UI configuration ### Prefilling (optional) Simple text signing supports prefilling of login-related fields when the end-user authenticates. Currently this applies to the national identification number (NIN) only. When enabled, additional login hints are collected from the authentication step. Prefilled values are shown to the end-user as part of the simple text signing screen. Prefill content varies by eID method, depending on what each method exposes. You can enable this behaviour through an optional parameter in your [signing session request](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions): ``` json "signer": { "nationalIdentificationNumber": "12345678910", "prefill": [ "NATIONAL_IDENTIFICATION_NUMBER" ] } ``` ### User interface behaviour You can specify two optional UI parameters that let you adjust how the flow appears. #### Hide welcome screen (optional) When `hideWelcomeScreen` is set to `true`, the welcome screen is not shown. The end-user is taken directly to the content that needs to be signed. To hide the welcome screen, include the following in your [signing session request](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions): ``` json "ui": { "hideWelcomeScreen": true } ``` #### Minimal text mode (optional) When `minimalTextMode` is set to true, a stripped down version of the signing interface is shown. Note that this only works if only a single `plain/text` document is included in the signing session. To use minimal text mode, include the following in your [signing session request](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions): ``` json "ui": { "minimalTextMode": true } ``` ## Signed result format After the user confirms the simple text, the API returns a signed result object that includes: - The text that was signed - Metadata about the signing - Details retrieved from the authentication method - Identity attributes available from the eID provider ### Response example ``` json "signatures": [ { "resultDocumentId": "019a3001-8f98-7e84-bb28-162a2c9059c5", "resultArchiveId": "id here" // if sendSigningResultsToArchive "originalDocumentId": "019a2ff4-cab0-7a61-b74e-dff3e9b2c18a", "signatureType": "XADES" } ], ``` --- ## Sign API v2 Our Sign API v2 is a REST API using European identity providers for creating electronic signatures on contracts, declarations, forms and other documents. ## Core capabilities - **OAuth2 for authentication**: Secure API authorisation using the industry standard. - **Customisable, responsive signing interface**: Tailor the signing flow and appearance to match your brand's look and feel across all devices. - **Standardised output formats**: Generate electronically signed files in compliant **XAdES** (XML Advanced Electronic Signatures) or **PAdES** (PDF Advanced Electronic Signatures) formats. ## Use case examples - **Collecting of signatures on multiple documents at the same time**: Coordinate complex signature workflows where multiple signers need to sign several related documents (such as rental or loan agreements). - **Business-to-business (B2B) signing and sealing (Merchant signing)**: Support sealing and signing transactions involving corporate invoices and certificates, registration and de-registrations in public movables registry, as well as company registrations. - **Frictionless consent capturing**: Record binding user consent for terms and conditions, GDPR updates or simple text statements. - **Long-term compliance & auditing**: Automatically transfer finalised signed contracts to a tamper-proof repository with strict retention management. - **Signicat Dashboard user management**: Securely control who can configure, monitor or manage your Sign API v2 integrations. ## Features and functionality We provide standalone guides for specialised functionality: * [**Archive**](/docs/electronic-signing/sign-api-v2/features/archive): Learn how to securely store signed documents in compliance with legal and regulatory requirements * [**Document collections**](/docs/electronic-signing/sign-api-v2/features/document-collections): Learn how to manage multiple documents and signing sessions with document collections * [**Merchant signing**](/docs/electronic-signing/sign-api-v2/features/merchant-signing): Learn how to implement business-to-business (B2B) signing with merchant certificates * [**Signature forwarding**](/docs/electronic-signing/sign-api-v2/features/signature-forwarding): Learn how to allow end-users to delegate signing sessions to others * [**Simple text signing**](/docs/electronic-signing/sign-api-v2/features/simple-text-signing): Learn how to implement simple text signing with Sign API v2 {/* ## Try it out * [**Demo**](): Try it out using our preconfigured demo service * [**Test in Dashboard**](): Learn how to test our Sign API v2 with your sandbox account and find available test users */} ## Guides {/* * [**Initial preparations**](): Learn about preparations before you start integrating */} * [**Integration guide**](/docs/electronic-signing/sign-api-v2/integration-guide): Follow step-by step guides to integrate with our Sign API v2 * [**Features and functionality**](/docs/electronic-signing/sign-api-v2/features/): Explore the features and functionality of our Sign API v2 * [**Signing methods**](/docs/electronic-signing/sign-api-v2/signing-methods): Browse supported authentication-based and PKI signing methods ## API reference Explore our Sign API v2 reference documentation to look up all API endpoints and properties as well as view sample requests and responses. * [**Sign API v2 API reference**](/apis/electronic-signing/sign-api-v2): Regulatory compliant electronic signatures ## Support * [**Core concepts**](/docs/electronic-signing/sign-api-v2/core-concepts/): Understand key terms and how they differ from our previous electronic signature APIs * [**Error codes**](/docs/electronic-signing/sign-api-v2/error-codes): Learn how to interpret error codes from Sign API v2 * [**Release notes**](/docs/electronic-signing/sign-api-v2/release-notes): Read about the latest Sign API v2 features and functionality To learn more, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Sign API v2 integration guide ## Set up an API integration Setting up an API integration is the most flexible way of testing our signature solutions. You can use your preferred IDE, framework, Postman, etc. using credentials provided by Signicat. :::tip Before you start the integration Before you set up an API integration, we recommended that you familiarise yourself with the most common integration [use cases](/docs/electronic-signing/sign-api-v2/#use-case-examples) and the [OpenAPI reference documentation](/apis/electronic-signing/sign-api-v2/) to learn about available endpoints and their properties. If you are looking for an automated business-to-business (B2B) signing and sealing process that does not require end-user interaction, see our [Merchant signing](/docs/electronic-signing/sign-api-v2/features/merchant-signing) feature guide. ::: ## Using the API The most basic signature process will consist of the following steps: 1. [Prerequisites](#1-prerequisites). 2. [Upload a document](#2-upload-a-document). 3. [Create a document collection](#3-create-a-document-collection). 4. [Create a signing session](#4-create-a-signing-session). 5. [Redirect the end-user to the signature application](#5-redirect-the-end-user-to-the-signature-application). 6. [Get the result from the signing session](#6-get-the-result-from-the-signing-session). 7. [Download the signed document](#7-download-the-signed-document). :::tip Note The code snippets below are kept brief for clarity and are provided as examples, not production code. For example, error handling is omitted. ::: ### 1. Prerequisites Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **Signature API** for your API client. ::: ### 2. Upload a document Once you have obtained an access token, you're ready to upload your first document to be signed. We support both PDFs and plain text documents, and the operation is as simple as making an HTTP POST request with the document's binary data to the [Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents) of the API. There is no Base64 conversion or similar. You simply read the document as binary data and send it directly to the server. :::warning Important We do not currently support signing of already signed PDFs or text files for authentication-based signing. If an end-user tries to sign an already signed document, the signing process may fail. We do support signing already signed PDF files with PKI signing (for example, [Norwegian BankID PKI signing](/identity-methods/nbid/integration-guide/sign-nbid/#limitations)). ::: #### Request example in Python ``` Python def upload_document(access_token, filename, content_type='application/pdf'): url = 'https://api.signicat.com/sign/documents' document_headers = { 'content-type': content_type, 'authorization': 'Bearer ' + access_token, } with open(filename, 'rb') as file: response = requests.post(url, headers=document_headers, data=file) return response.json()['documentId'] ``` In the code snippet above, you can see that we're extracting and returning the `documentId` from the response JSON. #### Response example The full response to the [POST request to the Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents/operation/uploadDocument) looks like this: ``` json { "mimeType": "application/pdf", "documentId": "0197d5cb-d683-7451-9b21-1a2da906b353", "createdAt": "2025-07-04T14:16:35.202871056Z", "documentHash": { "hash": "Y2QyOGVkNGMzZjUwNzU3OWQzMTM4YmRiZjRiOTU0MWViNGQ0MGI2MjAzNGMzNzFlNzg3ZGM1YmU0OGE0MzBlZg==", "hashAlgorithm": "SHA256" } } ``` If you want to upload a text document instead, just change the `content-type` header to `text/plain`. :::tip Note The document will remain on the server for 30 minutes, after which it will be deleted unless it has been used in a subsequent signing session. Once you add the document to a signing session, the session determines the document's retention period. By default, documents in a signing session are kept for 45 days. ::: ### 3. Create a document collection Once you have uploaded the document, the next step is to create a document collection. A document collection is a logical grouping of documents that will be signed together. This allows you to manage multiple documents in a single signing session. :::tip Note - For more information on the concepts and terminology of the API, see our [Sign API v2 terminology](/docs/electronic-signing/sign-api-v2/core-concepts/concepts/) page. - Learn how to manage multiple documents and signing sessions with document collections in our [Document collections](/docs/electronic-signing/sign-api-v2/features/document-collections/) feature guide. ::: In this tutorial, the document collection only has a single document in it. To create the document collection, you make a [POST request to the Document collections endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Document-collections/operation/createDocumentCollection) with a JSON structure containing the `documentId` you obtained in the previous step. #### Request example in Python ``` python def create_document_collection(access_token, document_id): url = 'https://api.signicat.com/sign/document-collections' document_collection_headers = { 'content-type': 'application/json', 'authorization': 'Bearer ' + access_token, } data = { "documents": [ { "documentId": f"{document_id}", } ] } response = requests.post(url, headers=document_collection_headers, data=json.dumps(data)) return response.json()['id'] ``` In the code snippet above, you are returning the `id` of the document collection response, since you'll be needing it in the next step. #### Response example The full response to the [POST request to the Document collections endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Document-collections/operation/createDocumentCollection) has the following format: ``` json { "id": "0197d5cb-dbbd-7e4d-b95c-9f2920882733", "documents": [ { "documentId": "0197d5cb-d683-7451-9b21-1a2da906b353" } ] } ``` ### 4. Create a signing session Equipped with the `documentId` and the `documentCollectionId` you previously obtained, you're now ready to create a signing session, which specifies the details for the end-user experience as well as the outcome of the signature process. To create a signing session, you need to make an HTTP POST request to the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions) with a JSON structure that includes the `documentId` and the `documentCollectionId`. The best way to illustrate how this is done, in its simplest form, is to look at some example code. #### Request example in Python ``` python def create_sign_session(access_token, document_collection_id, document_id): external_reference = str(uuid.uuid4()) url = 'https://api.signicat.com/sign/signing-sessions' sign_session_headers = { 'content-type': 'application/json', 'authorization': 'Bearer ' + access_token, } data = [ { "title": "The title of the signing session", "externalReference": f"{external_reference}", "documents": [ { "action": "SIGN", "documentCollectionId": f"{document_collection_id}", "documentId": f"{document_id}" } ], "signingSetup": [ { "identityProviders": [{ "idpName": "ftn" }], "signingFlow": "AUTHENTICATION_BASED" } ], "packageTo": ["PADES_CONTAINER"], "ui": { "language": "fi", }, "redirectSettings": { "error": f"https://www.example.com?q=error&externalReference={external_reference}", "cancel": f"https://www.example.com?q=cancel&externalReference={external_reference}", "success": f"https://www.example.com?q=success&externalReference={external_reference}" } } ] response = requests.post(url, headers=sign_session_headers, data=json.dumps(data)) return response.json()[0]['id'], response.json()[0]['signatureUrl'] ``` The following is an explanation of each field and its role in the request: - `title`: All signing sessions must have a title. In certain end-user configurations, this title will be displayed to the end-user. An example of an appropriate title could be "Rental agreement between X and Y". - `externalReference`: This field is intended for you to put your own internal identifier on the signing session, so that you can correlate it with the relevant process on your side. Note also that in this example, we're appending the external reference parameter to the redirect URLs so that, when the end-user returns to our application, we will know the context of the signature. - `documents`: In our simple one-document scenario, this array contains a single object with three fields: - `documentCollectionId` and `documentId` identify the document. - `action` specifies what the end-user is expected to do: Here, it's `SIGN`. - `signingSetup`: This array contains the options for the signature process: - `identityProviders` specifies which identity providers should be available to choose from for the end-user. If you don't specify this, then all configured identity providers on the account will be shown as options. In our example, we are using Finnish Trust Network (FTN). - In our simple scenario, we set `signingFlow` to `AUTHENTICATION_BASED`. Other options are available but omitted here for brevity. - `requestedAttributes` (optional): You can request identity provider-specific extra attributes by including a `requestedAttributes` array inside the `signingSetup` object. If supported by the IdP, the requested `requestedAttributes` will then be available under `output.userInfo.extra` in the signing session GET response. The following example requests two `nbid` attributes: ```json "signingSetup": [ { "identityProviders": [ { "idpName": "nbid" } ], "signingFlow": "AUTHENTICATION_BASED", "requestedAttributes": ["nbidAuthTime", "nbidSubjectUuid"] } ] ``` Note: Not all attributes are guaranteed to be available for every IdP. Availability depends on the IdP, user consent, and IdP-side behaviour. Contact your Signicat account manager or [Signicat Support](https://www.signicat.com/contact/contact-support) for current attribute availability. :::tip Note You can find provider-specific Sign API v2 integration guides in our ID methods documentation: - [Norwegian BankID](/identity-methods/nbid/integration-guide/sign-nbid.mdx) - [Swedish BankID](/identity-methods/sbid/integration-guide/sign-sbid.mdx) ::: - `packageTo`: Here, we want the signed document to be a PAdES (PDF Advanced Electronic Signatures), so we set it to `PADES_CONTAINER`. - `ui`: The settings in this object will affect the user interface, for example `language`. - `redirectSettings`: This object specifies where the end-user should be redirected after signing. It is not mandatory to set redirect URLs. If you do not specify them, the end-user will terminate the signature process at a completion page provided by Signicat. - `usageTags` and `notifications` (optional): These objects allow you to attach tags to a signing session to help correlate events and outgoing messages with your systems. - `usageTags` can be forwarded with billing and usage events so you can subscribe or filter events by tag. See our [Events and webhooks documentation](/docs/dashboard/settings/events.mdx) for more information on events and how to set up a webhook subscription. - `notifications` can be included with outgoing communication messages (email, SMS) so that messages can be correlated or filtered by tag. You can also define the content of the message, including sender details, headers and the text itself. The following example shows how you can configure both usage tags and notifications: ```json { "usageTags": [ "billing-tag-project-alpha", "event-tag-h1-2026-report" ], "notifications": [ { "communicationMethod": "EMAIL", "category": "SIGNING_NOTIFICATION", "tags": ["new-hire-contract", "email-notification"], "message": { "language": "en", "header": "Your document is ready for signing", "text": "Please review and sign the attached document.", "senderName": "HR Department", "senderAddress": "hr@yourcompany.com" } }, { "communicationMethod": "SMS", "category": "SIGNING_NOTIFICATION", "tags": ["urgent-signing", "sms-notification"], "message": { "language": "en", "text": "Urgent: A document requires your signature." } } ] } ``` :::tip Note For more information on the available properties, see the schema definitions for `NotificationMessage` and `NotificationMessageContent` under the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions) in our API reference. ::: For more information on all available fields and their purpose, see [our Sign API v2 reference](/apis/electronic-signing/sign-api-v2). #### Response example The response to the [POST request to the Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions/operation/createSigningSession) will be a full JSON structure in the following format: ``` json [ { "id": "0197d5fb-d3ce-70c0-a420-68972e1c4d57", "signatureUrl": "https://example.sandbox.signicat.com/sign?sessionId=0197d5fb-d3ce-70c0-a420-68972e1c4d57", "title": "The title of the signing session", "dueDate": "2025-08-03T15:09:00.139911468Z", "documents": [ { "documentCollectionId": "0197d5fb-d2bd-780a-8102-dd126ad41396", "action": "SIGN", "documentId": "0197d5fb-cc53-7514-8f69-df73c879f22c" } ], "lifecycle": { "state": "READY", "stateIsFinal": false }, "output": { "signatures": [], "packages": [] }, "externalReference": "85950a80-aba0-453d-be77-f75d20adbc9e", "signingSetup": [ { "identityProviders": [{ "idpName": "ftn" }], "signingFlow": "AUTHENTICATION_BASED", "additionalParameters": {} } ], "subsequentTo": [], "packageTo": [ "PADES_CONTAINER" ], "ui": { "language": "fi" }, "redirectSettings": { "error": "https://www.example.com?q=error&externalReference=85950a80-aba0-453d-be77-f75d20adbc9e", "cancel": "https://www.example.com?q=cancel&externalReference=85950a80-aba0-453d-be77-f75d20adbc9e", "success": "https://www.example.com?q=success&externalReference=85950a80-aba0-453d-be77-f75d20adbc9e" } } ] ``` In our example, we are mostly interested in the signing session `id`, as well as the `signatureUrl` which we will use to redirect the end-user. In a real-world application, you would typically store at least the signing session `id` and the `externalReference` in a database so that you can correlate them later. ### 5. Redirect the end-user to the signature application Once you have created the signing session, you can direct the end-user to the `signatureUrl` provided in the response. This URL will take them to the signing interface where they can complete (or cancel) the signing process. You then wait for the user to return to your application. ### 6. Get the result from the signing session In our example, we would like the signed document to be a signed PDF, a PAdES document. We refer to the process of converting the raw, signed document to a PAdES as **packaging**, meaning that the document is packaged into a PAdES container for easy viewing in supported PDF readers. However, packaging is an asynchronous process. This means that when the end-user returns to your application after signing, the PAdES is most likely not produced yet. The time it takes to complete the packaging is not guaranteed, so you should not poll API endpoints to await the result and keep the end-user waiting in the meantime, as the user experience would suffer. Instead, you set up a webhook in order to get notified when packaging has been completed. #### Configure a webhook subscription Setting up a webhook is a simple operation that you manage yourself in the [Signicat Dashboard](https://dashboard.signicat.com). To learn how to do this, see the [Add a subscription](/docs/dashboard/settings/events.mdx#add-a-subscription) section in our **Events and webhooks** documentation. In our example, we have set up a webhook subscription for the events 'Packaging completed' and 'Packaging failed', under the 'Signature' label in the Dashboard. Example for a webhook subscription for two events When packaging has completed, our application receives a webhook message with the following payload: ``` json { "id": "5ddcfab1-31a9-4660-b0b6-63eecebcedfc", "timestamp": "2025-07-04T15:51:58.8654531Z", "eventName": "package.completed", "sender": "signature", "eventData": { "id": "0197d5fb-d3ce-70c0-a420-68972e1c4d57", "externalId": "85950a80-aba0-453d-be77-f75d20adbc9e" }, "accountId": "a-spge-aCVRlHJKfdhjkhscfd40", "expiresAt": "2025-07-04T15:53:58.8654527Z", "isMockEvent": false, "tags": [] } ``` Inside the `eventData`, we find the `id`, which is the signing session ID and `externalId`, which is the `externalReference`. At this point, we will now call the Signing sessions endpoint to retrieve the document ID of the PAdES document and then we will download it. #### Retrieve the document ID of the PAdES document To retrieve the document ID of the PAdES document, you need to make an [HTTP GET request to the Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions/operation/getSigningSession) using the signing session ID you received in the webhook. ##### Request example in Python ``` python {11-13} def get_sign_session(access_token, session_id): url = f"https://api.signicat.com/sign/signing-sessions/{session_id}" sign_session_headers = { 'authorization': 'Bearer ' + access_token, } response = requests.get(url, headers=sign_session_headers) sign_session_response = json.loads(response.content) output = sign_session_response.get('output', {}) packages = output.get('packages', []) pades = packages[0] if packages else None pades_document_id = pades.get('resultDocumentId') if pades else None return pades_document_id ``` In the code snippet above, shown on lines 11-13, we extract the document ID of the PAdES from the response. ##### Response example The response to the [GET request to the Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions/operation/getSigningSession) is, again, the full signing session data structure, which will now contain updated information regarding the status of the process, as well as the relevant document identifiers. ``` json { "id": "0197d5fb-d3ce-70c0-a420-68972e1c4d57", /* REMOVED FOR BREVITY */ "lifecycle": { "state": "SIGNED", "stateIsFinal": true }, "output": { "signatures": [ { "resultDocumentId": "0197d623-1dae-7ea6-88f9-8474d83dbf97", "originalDocumentId": "0197d622-d70d-73de-8e73-d3f742c8d881", "signatureType": "XADES" } ], "packages": [ { "packageId": "0154e96f-4ff8-448b-bd22-6401cfa13180", "resultDocumentId": "0197d623-2b90-75e5-be3b-138fe89dfe38", "packageType": "PADES_CONTAINER" } ] }, /* REMOVED FOR BREVITY */ } ``` ### 7. Download the signed document All that remains now is to download the PAdES document. To download the PAdES, you need to make an HTTP GET request to the [Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents) of the API using the document ID you obtained in the previous step. #### Request example in Python ``` python def download_document(access_token, document_id): url = f'https://api.signicat.com/sign/documents/{document_id}' document_headers = { 'authorization': 'Bearer ' + access_token, } response = requests.get(url, headers=document_headers) return response.content ``` The response contains the binary content of the PAdES document. You can now save it as a PDF file to complete the process. ## Other integration details ### Signing by multiple signers You can also use the Sign API v2 to have the same document signed by multiple signers. This process builds on the single-signature flow described above, but with key differences depending on whether you are using **Authentication-based** or **PKI-based** signing. #### Authentication-based signing (parallel) For authentication-based signing (for example, Freja, MitID, FTN, iDIN, SMS OTP, Email OTP), the process allows multiple signers to sign a document in parallel. The process consists of the following steps: 1. [Upload a document](#2-upload-a-document) and [create a document collection](#3-create-a-document-collection) as described in steps 2 and 3 above. 2. For each person who needs to sign, create a separate signing session by making an HTTP POST request to the [Signing sessions endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Signing-sessions). Use the **same** `documentCollectionId` and `documentId` for each request. 3. Each request will return a unique `signatureUrl`. Distribute each URL to the corresponding signer. 4. After all parties have signed, you retrieve the final document from the parent document collection. See the section on [Retrieving the signed document for multi-sign](#retrieving-the-signed-document-for-multi-sign) for more information. #### PKI-based signing (sequential) For PKI-based signing, the underlying signature technology requires signatures to be applied sequentially. - **Norwegian BankID PKI signing**: We support a flexible, unordered signing workflow with an automatic locking mechanism. See the section on [Flexible, unordered signing with locking mechanism](#flexible-unordered-signing-with-locking-mechanism) below for more details. - **Other PKI-based signing methods**: (For example, Swedish BankID PKI signing) For other PKI methods, parallel signing sessions on the same document are not supported. Signers must sign sequentially. You must create a signing session, wait for the signature, and then use the signed result document to start the next signing session. #### Flexible, unordered signing with locking mechanism When using Norwegian BankID PKI, multiple signers can sign the document in any order (unordered signing). Because PKI signing requires modifying the document sequentially, Sign API v2 handles this using an automatic **locking mechanism for Norwegian BankID PKI signing**. You can now send a document to multiple signers at the same time without setting a predefined signing order: 1. Upload your document and create a document collection. 2. For each person who needs to sign, create a separate signing session by making an HTTP POST request to the [Signing sessions endpoint](/apis/electronic-signing/sign-api-v2/#tag/Signing-sessions). Use the **same** `documentCollectionId` and `documentId` for each request. 3. Distribute the unique `signatureUrl` returned in the response to the corresponding signers. 4. The signers can access the document in any order. ##### User experience (Locking) Since the system still technically seals the signatures sequentially in the background, only one signer can actively sign the document at a time. If a signer attempts to sign while another is already doing so, the system will temporarily lock the session and display a message asking them to try again shortly. Signer waiting screen when document is locked by another active signer #### Retrieving the signed document for multi-sign When a document has been signed by multiple signers, you do not download the result from one of the individual signing sessions. Instead, you must retrieve it from the parent document collection. 1. Get the document collection by its ID: Make an HTTP GET request to the [Document collections endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Document-collections/operation/getDocumentCollection), using the `collectionId` you used for all the signing sessions. 2. Extract the `resultDocumentId`: In the response, you will find a `resultDocumentId` field. This ID points to the final PAdES document containing all the signatures. **Response example** ```json { "id": "019914ae-53c9-7012-a868-2d047c27bc8c", "documents": [ { "documentId": "01990a8b-9bf4-7f6c-8b02-67557b096ed8", "description": "Terms of Service" } ], "resultDocumentId": "019914b0-1234-5678-9abc-3e058d28ad9d" } ``` 3. Download the final document: Use the `resultDocumentId` from the previous step to download the document by making an HTTP GET request to the [Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents/operation/getDocument), as described in [Step 7. Download the signed document](#7-download-the-signed-document). This will give you the single PDF file with all signatures applied. ### Signature forwarding Signature forwarding allows end-users to send a signing session to another person and nominate that person as a signer. For more information and a detailed example, see our [Signature forwarding](/docs/electronic-signing/sign-api-v2/features/signature-forwarding) feature guide. ### Simple text signing Simple text signing allows you to present a plain text string for the user to sign instead of a PDF document. This is ideal for scenarios like confirming terms and conditions or approving simple statements. For more information and a detailed example, see our [Simple text signing](/docs/electronic-signing/sign-api-v2/features/simple-text-signing) feature guide. ### Merchant signing Merchant signing (also known as sealing) allows your organisation to sign or seal documents automatically without any end-user interaction. This is typically used for business-to-business (B2B) processes, such as issuing electronic invoices, receipts or certificates that require a digital seal from the company. For more information and a detailed example, see our [Merchant signing](/docs/electronic-signing/sign-api-v2/features/merchant-signing) feature guide. ## API reference Explore our Sign API v2 reference documentation to look up all API endpoints and properties as well as view sample requests and responses. * [**Sign API v2 API reference**](/apis/electronic-signing/sign-api-v2): Regulatory compliant electronic signatures --- ## Release notes for Sign API v2 # Sign API v2 release notes {/* TEMPLATE ### DD.MM.YYYY
Expand/collapse release notes #### New features - *Summary.* Text goes here. #### Improved - *Summary.* Text goes here. #### Resolved issues - *Summary.* Text goes here.
--- */} ## 2026 ### 07.07.2026
Expand/collapse release notes #### New features - Swedish BankID (`sbid`) Public Key Infrastructure (PKI) signing #### Improved - Support for flexible, unordered signing with Norwegian BankID (`nbid`) PKI signing
### 03.03.2026
Expand/collapse release notes #### New features - Merchant signing: Support for business-to-business (B2B) signing with Norwegian BankID
### 06.01.2026
Expand/collapse release notes #### New features - Archive: Added support for archiving functionality via the `archive` object
## 2025 ### 31.10.2025
Expand/collapse release notes #### Improved - Improved PAdES (PDF Advanced Electronic Signatures) accessibility for European Accessibility Act (EAA) compliance
### 31.10.2025
Expand/collapse release notes #### New features - Added support for additional eID methods for signing
### 14.10.2025
Expand/collapse release notes #### New features - Expanded Signicat Dashboard capabilities for our Sign API v2: - Support for Elasticsearch for document name and document tags - Added quick filters - Expanded session details - Enhanced error handling #### Improved - Further enhancements on accessibility in the signing interface, aligning with Web Content Accessibility Guidelines (WCAG) standards
### 30.09.2025
Expand/collapse release notes #### New features - Norwegian BankID (`nbid`) Public Key Infrastructure (PKI) signing - Support for `SignText` field - `additionalParameters` supported for `mitid_app_type` to enable app switching - Support for `NO_USE` for `nationalIdentityNumber` - Separate packaging endpoint - Support for artifacts
### 11.09.2025
Expand/collapse release notes #### New features - Launched [Signicat Dashboard](https://dashboard.signicat.com) capabilities for our Sign API v2 - Added ability to search for and filter sessions and collections #### Improved - Enhanced accessibility in the signing interface, aligning with Web Content Accessibility Guidelines (WCAG) standards
### 19.08.2025
Expand/collapse release notes #### New features - Internal groundwork completed for future improvements and new features - Backwards compatibility in UI for Express API features #### Resolved issues - Miscellaneous bug fixes and minor improvements
### 14.08.2025
Expand/collapse release notes #### Improved - Monitoring and resilience improvements #### Resolved issues - Miscellaneous bug fixes
### 20.06.2025
Expand/collapse release notes #### New features - Support for certificate-based signing (through Buypass) now includes: - Support for Norwegian BankID #### Improved - Accessibility compliance improvements
### 19.05.2025
Expand/collapse release notes #### Improved - Miscellaneous improvements
### 29.04.2025
Expand/collapse release notes #### New features - Initial support for Dutch eID methods DigID and iDIN
### 11.04.2025
Expand/collapse release notes #### New features - Support for subject validation on a person's national identity number #### Improved - UI improvements
### 28.02.2025
Expand/collapse release notes #### New features - Initial support for certificate-based signing (through Buypass) #### Improved - UI improvements for mobile devices
## 2024 ### 13.12.2024
Expand/collapse release notes #### New features - Support for multiple documents - Support for multiple signers - PAdES (PDF Advanced Electronic Signatures) output
### 31.10.2024
Expand/collapse release notes #### New features - Initial support for phone flow signing with Swedish BankID #### Improved - UI improvements for use on mobile devices - New field `signatureURL` in the signing session response #### Resolved issues - Miscellaneous bug fixes
### 17.10.2024
Expand/collapse release notes #### Improved - UI improvements for use on mobile devices #### Resolved issues - Miscellaneous bug fixes
### 25.09.2024
Expand/collapse release notes #### New features - Single user, signing a single document producing an LTV-SDO (long-term validation signed data object) as evidence - End-user notifications when an action is needed - Customer-facing events channel for signing session state changes and creation
--- To learn more, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Signing methods Our Sign API v2 supports two main forms of electronic signatures: 1. **Authentication-based signing** (where the signature is backed by a verified authentication event) and 2. **PKI signing** (where the signature is cryptographically generated natively by the electronic identity scheme). ## Authentication-based signing **Authentication-based signing** supports the use of any type of authentication method provided by Signicat, where the authentication result is used for signing. This ensures a unified output format in accordance with EU specifications, as well as a scalable, responsive signing interface supporting all modern device standards and window sizes. Authentication-based signing enables you to sign one or more documents by first consenting to the contents of the document(s) and subsequently authenticating yourself using one of a number of eID providers. As the product relies on authentication, the eID providers do not need to support signing themselves. Our Sign API v2 gathers proof of the signer's actions, i.e. viewing the document(s), consenting to the contents and the authentication itself. The series of proofs is combined with each of the original documents. The result is a signed XML document (XAdES), which is digitally signed by Signicat. Each original document results in one XAdES document for each signer. The signed documents can also be merged into a final PAdES (PDF Advanced Electronic Signatures) document. ### Supported authentication-based signing methods :::CustomTable | eID method | Description | | :--- | :--- | | [Freja](/identity-methods/freja/) | Freja eID | | [MitID personal](/identity-methods/mitid/) | MitID for private entities | | [MitID business](/identity-methods/mitid/) | MitID for business entities | | [FTN](/identity-methods/ftn/) | Finnish BankID and Mobile-ID | | [IDIN](/identity-methods/idin/) | Digital identification service developed by the Dutch banking sector | | [SMS OTP](/identity-methods/sms-otp/) | SMS one-time password (OTP): A code sent to the signer's mobile device to confirm their identity. | | [Email OTP](/identity-methods/email-otp/) | Email one-time password (OTP): A code sent to the signer's email address for verification. | ::: {/* | [DigiD](/identity-methods/digid/) | (abbreviation for Digitale Identificatie) is the Dutch government's universal online digital identity system, allowing residents to securely authenticate themselves when using public services | */} {/* | [eHerkenning](/identity-methods/eherkenning/) | Standardised digital identity and login system for businesses and organisations in the Netherlands - essentially the corporate equivalent of DigiD | */} ## PKI signing **Public Key Infrastructure (PKI) signing** allows you to sign documents using the natively available signing capabilities of specific eID providers. In a PKI signing flow, the signature is cryptographically bound to the document using private keys managed by the eID provider or stored securely on the user's device (such as a hardware security module or smartcard). This produces a highly secure, non-repudiable signature compliant with local regulatory standards. The resulting signature can then be verified directly against the provider's trust infrastructure or packaged into standard PAdES containers. ### Supported PKI signing methods :::CustomTable | eID method | Description | | :--- | :--- | | [Norwegian BankID](/identity-methods/nbid/integration-guide/sign-nbid) | Norwegian BankID PKI signing | | [Swedish BankID](/identity-methods/sbid/integration-guide/sign-sbid) | Swedish BankID PKI signing | ::: {/* | [Freja](/identity-methods/freja/) | eID operating out of Sweden. Has multiple level signature products. | */} {/* | InkSign / Handwritten | InkSign allows signers to draw their signature on a touchscreen device, such as a smartphone or tablet. This signature is then embedded into the digital document, providing a visual representation of the signer's intent to agree to the document's contents. | */} ## UI and technical differences While standard authentication-based signing offers a uniform UI across methods, the end-user experience with PKI-based signing (`PKISIGNING`) depends on the provider and document type. ### Norwegian BankID For Norwegian BankID, the PKI-based signing flow looks similar in the UI to signing with `AUTHENTICATION_BASED` and selecting only the `nbid` eID. However, there are significant differences with PKI signing: - With `PKISIGNING`, the system creates signing certificates for Cloud Signature Consortium (CSC) solutions. - `PKISIGNING` provides QES-compliant signatures while `AUTHENTICATION_BASED` does not. - When the authentication is complete, the end-user will see a consent screen where they must give their consent before being redirected back to the signing interface or to the `redirectUri` defined in the signing session. ### Swedish BankID The behaviour of the end-user interface for Swedish BankID PKI signing depends on the number and type of documents you are signing. #### Signing a single text document When signing a single text document, Signicat's signing interface is skipped entirely and the end-user is redirected to the BankID application. - The document content (the text to be signed) is displayed directly within the Swedish BankID app. You must provide the text content for the document. - You can optionally provide an intention text that appears above the document content. If you do not provide one, the default value "You are about to sign the following document(s):" is displayed. The following is an example of the BankID application view for text documents: #### Signing multiple documents or PDFs When signing multiple documents (all text, all PDFs or a combination), Signicat's signing interface is displayed to the user before they are redirected to the Swedish BankID app. - The signing interface shows a preview of the documents to the user. - For PDF files, the file preview is not available in the BankID app itself. Instead, you can provide contextual text using the `signText` field in the `SigningSession` object. For example: "You are signing the document Agreement.pdf". - This contextual text supports Markdown formatting and is displayed in the BankID app. If no text is provided, a default message is shown. The following is an example of the BankID application view when contextual text is provided for a PDF: --- ## Identity document verification API # Assure API integration Learn how to integrate with different eIDV services, including PictureID, ReadID, VideoID, Onfido and WebID, through the Assure API. This page provides an overview of possible ways of integrating with the Assure API to verify the identity of a person using an ID document. :::note Prerequisites We assume you already know your client_id and client_secret and also have the access token (`OIDC_ACCESS_TOKEN`) that is required for calling each endpoint. This is described in the [Quick start guide](/docs/id-document-and-biometric-verification/quick-start-guides/quick-start-guide-assure-api/#set-up-an-api-integration). It is also assumed that you have access to the Assure API at some environment. ::: ## Introduction to the API * [**Key concepts**](/docs/id-document-and-biometric-verification/assure-api/key-concepts): Read about the key concepts in the Assure API before you start to integrate * [**General usage recommendations**](/docs/id-document-and-biometric-verification/assure-api/usage-recommendations/): Read about important setup recommendations before you start to integrate * [**Choose your preferred integration flow**](/docs/id-document-and-biometric-verification/assure-api/integration-flows): Choose either the generic or the alternative flow (web only) ## Integration guides * [**Integration guide for Assure API**](/docs/id-document-and-biometric-verification/assure-api/integration-steps): Follow these common steps for all providers * [**Provider-specific integrations**](/docs/id-document-and-biometric-verification/provider-specific-integrations/): Step by step setup instructions for each provider (PictureID, ReadID, VideoID, Onfido, WebID) ## Service details * [**Assure API services and endpoints**](/docs/id-document-and-biometric-verification/services/): Read more about central services for Assure API ## API Reference The Signicat Assure API is a single point of integration across [eIDV services](/docs/id-document-and-biometric-verification/#eidv-services). It enables you to combine a wide range of identity document verification mechanisms such as NFC reading of passports, fully automated verification using AI and manual verification performed by agents, based on the specific requirements for each individual end-user identity being verified. * [**Assure API**](/apis/id-document-and-biometric-verification/): Signicat's API for verifying identity documents --- ## Choose an integration flow This topic provides an overview of the flows for integrating with the Assure API and the use of its services. You can choose between the following flows: - [eIDV generic flow](#eidv-generic-flow) - [eIDV alternative flow (web only)](#eidv-alternative-flow-web-only) :::warning Important Your mobile/web app must always communicate with your own server and never directly with the Assure API. For more recommendations, see the [General usage recommendations page]. ::: ## eIDV generic flow By integrating with the Assure API, you enable an end-user to perform electronic identity verification using their identity document on your web/native mobile app. The generic flow for integrating this service can be illustrated as follows: ```mermaid sequenceDiagram title eIDV generic data flow participant FE as Service provider frontend participant BE as Service provider backend participant Assure as Assure API participant eIDV as eIDV verification provider rect rgb(247, 249, 252) note left of FE: 1. Initial setup BE->>Assure: Create dossier Assure-->>BE: dossierId BE->>Assure: Create process (dossierId, provider) Assure-->>BE: processId, authorizationUrl end rect rgb(247, 249, 252) note left of FE: 2. Upload ID images alt FE-->>eIDV: Alternative A: Use provider's SDK to capture and upload images (authorization token) else BE->>Assure: Alternative B: Upload images via backend Assure-->>eIDV: Forward images end end rect rgb(247, 249, 252) note left of FE: 3. Request verification BE->>Assure: Start verification (dossierId, processId) Assure-->>eIDV: Forward verification request end rect rgb(247, 249, 252) note left of FE: 4. Get result eIDV-->>Assure: Verification result Assure->>BE: process.complete event (dossierId, processId, status) BE->>Assure: Get process (dossierId, processId) Assure-->>BE: Process final result information end ``` ### Step 1: Initial setup Use the [Create dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier) endpoint to create a placeholder for all of your end-user's data: ```sh curl -X POST \ /assure/dossiers \ -H 'Accept: application/json' \ -H 'Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw' \ -H 'Content-Type: application/json' \ ``` Save the `dossierId` from the response body to use in the next requests. :::warning Note Ensure you use one dossier per end-user. ::: :::tip View the dossier contents After creating a dossier, you can see all of its contents anytime you want to. To do that, use the [Get dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/getDossiers) endpoint giving it the `dossierId`. ::: Use the [Create process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/createProcess) endpoint to create an identity verification process inside the dossier. Ensure you use the `dossierId` from the "Create dossier" response. The process allows you to request an [eIDV provider](/docs/id-document-and-biometric-verification/provider-specific-integrations/) to perform the verification of an identity document. It is also where all information about the [verification result](#step-4-get-verification-result) is kept. ### Step 2: Upload ID images Now that you have a dossier and a process, you must provide images of the identity document and of the end-user. You can do this either by using the provider's SDK to capture and upload the images or by uploading the images directly using the Assure API. See also [Images](/docs/id-document-and-biometric-verification/services/images.mdx). ### Step 3: Request verification Now that all the necessary information has been provided, you should [request the verification](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/startVerification). **Can I upload new ID images to the same process?** Every time you upload images to a process, they will replace the previous ones. However, as soon as you request the verification to be performed, no more images should be uploaded. If you need to change the images or any other data, you should discard the current process and create a new one. ### Step 4: Get verification result At this point, we must wait for a response from the provider with the final result. Since this response is obtained asynchronously, you may subscribe to [Assure Events](/docs/id-document-and-biometric-verification/services/callbacks.mdx) to be notified when the result is available. Still, at any time you can see all the available information about an identity document verification by [checking the information in the process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess). **Must I subscribe to Assure Events to get the final result?** You are not required to subscribe to the [Assure Events](/docs/id-document-and-biometric-verification/services/callbacks.mdx). However, we strongly recommend that you do this, instead of polling Signicat's services. :::warning Polling risk Using polling instead of subscribing to events, may put your service at risk due to rate limiting of requests. ::: The [final result information](/docs/id-document-and-biometric-verification/services/process.mdx#normalised-final-result) is always kept inside the process whether you asked to be notified or not. The event notification only informs you that the verification is finished. An important feature of the Assure API is that, regardless of the provider you use to perform the identity verification, you always get a normalised final result on any process that is “accepted”. For more information about the process results, see [Get process](/docs/id-document-and-biometric-verification/services/process.mdx). ## eIDV alternative flow (web only) If you prefer using the provider's SDK to capture and upload the ID images and you are integrating with the Assure API in a web environment, you can deflect integrating with their SDK and alternatively use the Assure API [Capture](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact) service. These services encapsulate the providers' JS SDKs, making it quicker and easier for you to integrate with the Assure API in a web context: ```mermaid sequenceDiagram title eIDV alternative data flow participant FE as Service provider frontend participant BE as Service provider backend participant Assure as Assure API participant eIDV as eIDV verification provider rect rgb(247, 249, 252) note left of FE: 1. Initial setup BE->>Assure: Create dossier Assure-->>BE: dossierId BE->>Assure: Start capture flow (dossierId, provider, redirectUrl) Assure-->>BE: url BE-->>FE: Redirect end-user to url end rect rgb(247, 249, 252) note left of FE: 2. Image upload + verification FE->>eIDV: End-user is redirected to SDK, uses it to capture/upload ID images and verification starts eIDV-->>Assure: Verification response Assure->>FE: Redirect end-user to redirectUrl+dossierId+processId+status end rect rgb(247, 249, 252) note left of FE: 3. Get result Assure-->>BE: process.complete event (dossierId, processId, status) BE->>Assure: Get process (dossierId, processId) Assure-->>BE: Process final result information end ``` This flow is a simplification of the [generic eIDV integration flow](#eidv-generic-flow). You don't need to create a process (step 1 in the generic flow), integrate with the provider's SDK / upload the images (step 2 in the generic flow) nor request to start the verification (step 3 in the generic flow). All of these steps are encapsulated in the [Start capture flow](/docs/id-document-and-biometric-verification/services/capture.mdx) service. :::warning Capture in iframe For security reasons, Capture will only successfully load inside ` --- ## VideoID VideoID is Signicat's own eIDV service for secure online customer onboarding. This service enables you to capture a video recording of an ID document and/or the end-user's face, with actions to prove liveness (for example, smile to the camera). You can integrate with VideoID by adding `signicatvideoid` as a provider in the Assure API. ## Supported features VideoID performs the following automated checks: - Face biometric scoring - Liveness detection (anti-spoofing) - ID document matching VideoID can be used either in a web or in a native (mobile) context. ## Product types Depending on the LoA requirements for your service, VideoID offers different levels of assurance (LoA): - [VideoID Substantial](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/#videoid-substantial) - [VideoID High](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/#videoid-high) :::tip VideoID product types and user flows If you want to read more about VideoID product type options and how it works for the end-user before you start integrating, see the [VideoID About](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/) page. ::: ## Guides VideoID is available as a `provider` in the Assure API. * [**Quick start guide**](/docs/id-document-and-biometric-verification/quick-start-guides/quick-start-guide-assure-api/): Get started with Assure API * [**Integration guide for VideoID**](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/): Learn how to integrate with VideoID through Assure API. --- ## VideoID integration guide This guide provides steps for integrating with VideoID through the **Assure API** for the following two use case scenarios: - [Use case 1: Use only Assure API's Capture service to capture and upload the image (web only)](#uc-1-use-only-assure-apis-capture-service-to-capture-and-upload-the-image-web-only) - [Use case 2: Use VideoID's native SDK to capture and upload the images (web or native mobile)](#uc-2-use-videoids-native-sdk-to-capture-and-upload-the-images-web-or-native-mobile) :::tip About VideoID If you want to know more about features and how this product can be used before you start integrating, see the high-level introduction to [VideoID](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/). ::: ## Prerequisites We assume you already have done the initial integration steps with the Assure API, see [Set up an API integration](/docs/id-document-and-biometric-verification/quick-start-guides/quick-start-guide-assure-api/#set-up-an-api-integration). ## UC 1: Use only Assure API's Capture service to capture and upload the image (web only) > I want to allow an end-user to verify their identity using the [Signicat VideoID SDK](https://www.signicat.com/identity-methods/videoid) provider in my website. > > I want the required ID images to be captured and uploaded using VideoID's SDK but I don't want to integrate with it. > > I also want to be able to retrieve the video of the verification process. > > In the end, I want to see all the information regarding the verification process. Afterwards, I want to delete the dossier (including all the end-user information). :::note This use case only fits web (JS) applications. ::: In this use case, you integrate _only_ with the Assure API. VideoID's Web (JS) SDK is embedded in the Assure API [Start capture flow](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact) service. ```mermaid flowchart LR Start@{ shape: sm-circ, label: "Small start" } --> A["A. Createdossier"]:::secondary subgraph " " direction TB Q1{"Use Assure API's integrated JSSDK service?"} Q1 -- N --> B["B. Get document types"] Q1 -- Y --> G["G. Start capture flow(only web)"]:::secondary end A --> Q1 B --> C["C. Create process"] C --> Q2{"Use provider's SDK to capture + upload ID images?"} Q2 -- Y --> D1["D1. Launchprovider's SDK"] Q2 -- N --> D2["D2. Upload images via Assure API(only some providers)"] D1 --> E["E. Startverification"] D2 --> E E --> F["F. Get process"]:::secondary G --> F ``` The green colour indicates the path you should take for this use case. This use case path is described in more detail below, using the same step numbers as in the diagram. ### Step A: Create dossier Use the [Create dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier) endpoint to create a placeholder for all of your end-user's data: ```sh curl -X POST \ /assure/dossiers \ -H 'Accept: application/json' \ -H 'Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw' \ -H 'Content-Type: application/json' \ ``` Save the `dossierId` from the response body to use in the next requests. :::warning Note Ensure you use one dossier per end-user. ::: :::tip View the dossier contents After creating a dossier, you can see all of its contents anytime you want to. To do that, use the [Get dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/getDossiers) endpoint giving it the `dossierId`. ::: ### Step G: Start capture flow Use the [Start capture flow](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact) endpoint to create an identity verification process in a web context. The Capture service helps capturing and uploading ID images from the identity verification process. #### Request To start the flow, send a POST request to `https://api.signicat.com/assure/dossiers/{dossierId}/capture` In the [Start capture flow](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact) request, ensure you: - Use the `dossierId` from the "Create dossier" response. - Specify the `redirectUrl` to redirect the user to the required page after the verification is finished. Here is an example of a basic request: ```sh curl --location 'https://api.signicat.com/assure/dossiers//capture' \ --header 'Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "providers": [ { "provider": "signicatvideoid", "processType": "substantialFullyAuto" } ], "redirectUrl": "" }' ``` For other optional parameters in this request, see the [API Reference > Start capture flow](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact). #### Redirect the end-user to the identity verification In the "Start capture flow" response, you receive a URL, for example: ```json { "url": "https://assure-demo.sandbox.signicat.com/capture/#/artifact=4f24sdq2pcs1m5dymx8zfvdft8g1ns3getdx41ar222e3smkoh" } ``` - You must use this URL to redirect the end-user to the identity verification UI (on desktop or mobile), where they can perform their identification. - After the end-user has identified themselves, they are redirected to the specified `redirectUrl` you sent in the request. - Then wait for the notification to arrive before you proceed to the **Get process** step to get the result (see below). :::tip Assure Events It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see [Assure Events](/docs/id-document-and-biometric-verification/services/callbacks/). ::: ### Step F: Get process Retrieve the result information with the following endpoints, using the `dossierId` and `processId` from the previous steps (or from the [Assure event notification](/docs/id-document-and-biometric-verification/services/callbacks.mdx)): - [Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess): The response contains data about the process final result (for more information, see [Final result status](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/service-details/#final-result-status)). - [Get video](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getVideo): Get a video of the end-user capturing images of the identity document. - [Download full result](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getZipFile): Download all the information regarding the process (for more information, see [Download full result](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/service-details/#download-full-result)). :::tip Delete the dossier After you have finished the end-user verification, it is recommended to [delete the dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/deleteDossier). This deletes all the information about this end-user. See also the [General usage recommendations](/docs/id-document-and-biometric-verification/assure-api/usage-recommendations/#save-useful-information-and-clean-up-afterwards) section. ::: ## UC 2: Use VideoID's native SDK to capture and upload the images (web or native mobile) > I want to allow the same end-user from the previous use case to verify their identity, but now using the [Signicat VideoID SDK](https://www.signicat.com/identity-methods/videoid). > > In the end, I want to receive a **final result with the same structure** as the one from the test case before (despite having used a different provider). > > I also want to see the information about **all processes from this end-user**. :::tip Tip This use case seamlessly fits both web (JS) and native mobile (Android/iOS) applications. ::: VideoID always requires that the ID images are captured and uploaded using its native SDK. ```mermaid flowchart LR Start@{ shape: sm-circ, label: "Small start" } --> A["A. Createdossier"]:::secondary Q1{"Use Assure API's integrated JSSDK service?"} Q1 -- N --> B["B. Get document types"]:::secondary Q1 -- Y --> G["G. Start capture flow(only web)"] A --> Q1 B --> C["C. Create process"]:::secondary C --> Q2{"Use provider's SDK to capture + upload ID images?"} subgraph " " direction TB Q2 -- Y --> D1["D1. Launchprovider's SDK"]:::secondary Q2 -- N --> D2["D2. Upload images via Assure API(only some providers)"] end D1 --> E["E. Startverification"]:::secondary D2 --> E E --> F["F. Get process"]:::secondary G --> F ``` The green colour indicates the path you should take for this use case. This use case path is described in more detail below, using the same step numbers as in the diagram. ### Step A: Create dossier Use the [Create dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier) endpoint to create a placeholder for all of your end-user's data: ```sh curl -X POST \ /assure/dossiers \ -H 'Accept: application/json' \ -H 'Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw' \ -H 'Content-Type: application/json' \ ``` Save the `dossierId` from the response body to use in the next requests. :::warning Note Ensure you use one dossier per end-user. ::: :::tip View the dossier contents After creating a dossier, you can see all of its contents anytime you want to. To do that, use the [Get dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/getDossiers) endpoint giving it the `dossierId`. ::: ### Step B: Get document types When integrating with the VideoID SDK, you must specify the ID of the document that will be used to verify the identity. To get that document ID, you must use the [getDocumentTypes](pathname:///apis/id-document-and-biometric-verification/#tag/Assure/operation/getDocumentTypes) endpoint to get the list of documents supported by VideoID in your environment. :::tip Enable more document types VideoID supports more documents than the ones listed in the getDocumentTypes response, but they must be explicitly enabled. If you need to enable more documents, please [create a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ### Step C: Create process Use the [Create process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/createProcess) endpoint to create an identity verification process inside the dossier. Ensure you use the `dossierId` from the "Create dossier" response. - Set the `provider` to `signicatvideoid`. Here is an example JSON request body: ```json { "provider": "signicatvideoid", "processType": "high", } ``` Save the `authorizationToken` and the `processId` from the response to be used in the next step. ### Step D1: Launch provider's SDK Now you must launch the SDK in your app. For more information about how to do this, see the [Mobile SDKs](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/sdks/#3-integrate-with-the-videoid-native-mobile-sdks) section. ### Step E: Start verification VideoID High requires that a manual approval of each verification request is performed using their Registration Authority Application (RA App). - Access VideoID's Registration Authority App. {/*If you don't have the link to that app, use the [Get Manual Approval URL](pathname:///apis/id-document-and-biometric-verification/#tag/getManualApprovalUrl) endpoint to get it.*/} - Select **Start to work**. - Accept a verification request. Go through the indicated steps and register the verification. :::note Register the verification It is important to register the verification since it marks the process as `accepted`. If you reject it, the process status in the next step will be returned as `rejected` and you will not get a `finalResult` element in the response body. ::: ### Step F: Get process - Use the `dossierId` and `processId` from the previous steps (or from the [Assure event notification](/docs/id-document-and-biometric-verification/services/callbacks.mdx), in case you use it). - The process status is now `accepted` and the response body contains data about the process final result (for more details, see [Final result status](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/service-details/#final-result-status)). - All information is [normalised](/docs/id-document-and-biometric-verification/assure-api/key-concepts.mdx#normalisation) and the `finalResult` element contains the same fields of information as the final result of the accepted VideoID requests in the previous use cases. - Get dossier: Finally, to check the information about all processes regarding this end-user, call the [Get dossier](pathname:///apis/id-document-and-biometric-verification/#tag/getDossier) endpoint. :::tip Delete the dossier After you have finished the end-user verification, it is recommended to [delete the dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/deleteDossier). This deletes all the information about this end-user. See also the [General usage recommendations](/docs/id-document-and-biometric-verification/assure-api/usage-recommendations/#save-useful-information-and-clean-up-afterwards) section. ::: ## More guides * [**Integrate through Assure using the VideoID SDKs**](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/sdks/): Learn how to integrate using the VideoID native mobile SDKs (Android and iOS) * [**Assure API service details for `videoid**](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/service-details/): Learn more about the `videoid` provider specific settings --- ## Mobile SDKs (Android and iOS) The aim of this topic is to help a developer integrating with the Assure API using VideoID's native mobile SDKs. This is a more detailed description of [Use case 2 in the Integration guide](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/integration-guide-videoid/#uc-2-use-videoids-native-sdk-to-capture-and-upload-the-images-web-or-native-mobile). Using the VideoID's native SDKs means that the end-user will see Signicat VideoID's *user interface* when performing the identity verification on their mobile. For more information about the identity verification steps seen from the end user, see the high-level [VideoID](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/) page. :::note Documentation scope Please, keep in mind that the following descriptions do not contain all the necessary steps for production mode. In addition, you must add validations, tests and error handling, which is outside the scope of this documentation. Before you start the SDK integration, we recommend to familiarise yourself with the [general steps](/docs/id-document-and-biometric-verification/assure-api/integration-steps.mdx) for integrating with the Assure API. ::: ## Requirements Before you start the SDK integration, you should be aware of the following requirements for VideoID's mobile SDKs: - We advise you to always use the latest VideoID SDK version: - Android: API level 24, Android 7 - iOS: 10.0 and higher - Check the supported device versions: - Android: 4.0 or later - iPhone: 5S or higher - The app needs camera and microphone permission. - Your app must always communicate with your own server and **never directly with the Assure API** (see [Usage recommendations](/docs/id-document-and-biometric-verification/assure-api/usage-recommendations/)). - Since you are integrating with the Assure API in a native app context, you should choose the [eIDV generic flow.](/docs/id-document-and-biometric-verification/assure-api/integration-flows.mdx#eidv-generic-flow) ## Integration steps overview The next sections describe all the _necessary_ steps, including the integration with Assure before and after the VideoID SDK integration in step 3: 1. [Create a dossier.](#1-create-dossier) 2. [Create a process.](#2-create-process) 3. [Integrate with the VideoID native mobile SDK to check the ID document, facial similarity and liveness.](#3-integrate-with-the-videoid-native-mobile-sdks) 4. [Start verification.](#4-start-verification) 5. [Get result.](#5-get-result) :::tip Note: All the steps are similar for iOS and Android except the SDK integration in step 3, which is described below in for [iOS](#ios) and [Android](#android). ::: ## 1. Create dossier Use the [Create dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier) endpoint to create a placeholder for all of your end-user's data: ```sh curl -X POST \ /assure/dossiers \ -H 'Accept: application/json' \ -H 'Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw' \ -H 'Content-Type: application/json' \ ``` Save the `dossierId` from the response body to use in the next requests. :::warning Note Ensure you use one dossier per end-user. ::: :::tip View the dossier contents After creating a dossier, you can see all of its contents anytime you want to. To do that, use the [Get dossier](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/getDossiers) endpoint giving it the `dossierId`. ::: ## 2. Create process To be able to create a process, you need to get some information from your mobile app, send it to your backend server and afterwards to the Assure API. Here is an example request: ```json { "provider": "signicatvideoid", "processType": "substantialFullyAuto", } ``` :::tip processType The value depends on the checks you want to perform. You can choose between: - `high`: A human agent will review the identity verification video asynchronously. - `substantialFullyAuto`: Process verification is done automatically, meaning no human agent is involved. This is similar to `substantial`, but without any inconclusive status. This is the recommended process type (see more details on the high-level [VideoID](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/about-videoid/#videoid-substantial) page) - `substantial`: Process verification is done automatically, meaning no human agent is involved. ::: ### Response example Here is an example response for Create process: ```json { "processId": "7a3a6648-4c8b-421f-a8c3-843677c3d398", "provider": "signicatvideoid", "processType": "substantialFullyAuto", "status": "pending", "authorization": "IR3kAtY6-GDS0dBG-a3MAtVkIEZl4lOH5DEc2HJzSYytV57xGn3Ixa9wJLhV9Tt2_OxjCD3EOUpZTX7Dj-IeSacMpY_XhMWhv6iVIcSz9l8=", "providerApiUrl": "https://etrust-live.electronicid.eu/v2", "createdAt": "2025-11-14T11:48:36Z", "updatedAt": "2025-11-14T11:48:36Z" } ``` Save the information from the response. You will need it in the next steps. ## 3. Integrate with the VideoID native mobile SDKs To start the identity verification user flow, you must now integrate with the VideoID SDK for either [Android](#android) or [iOS](#ios): ### Android #### Import the SDK The SDK is distributed as an `.aar` package from a public repository. Add the repository to your project's `build.gradle` file: ```groovy allprojects { repositories { maven { url "https://repo.electronicid.eu/repository/android-sdk-releases/" } } } ``` Then, add the dependency: ```groovy dependencies { implementation 'eu.electronicid.android:sdk:1.+' } ``` #### Initialise and run the SDK (Kotlin example) You must send the `authorization` field that you received in the backend response to the mobile app. To integrate the VideoID service, launch the `VideoIDActivity`. The result of the identification will be returned in the `onActivityResult` method. :::note Environment URL Ensure you replace the below environment URL, `https://`, with the `providerApiUrl` value that you received in the [Create process reponse](#response-example). ::: ```kotlin // In a button click listener, for example val intent = Intent(this, VideoIDActivity::class.java).apply { putExtra( VideoIDActivity.ENVIRONMENT, Environment(URL("https:///"), authorizationToken) ) putExtra(VideoIDActivity.LANGUAGE, "en") // e.g., "es", "fr", "de" } startActivityForResult(intent, REQUEST_CODE) // Handle the result override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == REQUEST_CODE) { if (resultCode == Activity.RESULT_OK) { val videoId = data?.getStringExtra(VideoIdServiceActivity.RESULT_OK) // Process successful verification } else if (resultCode == Activity.RESULT_CANCELED) { val errorId = data?.getStringExtra(VideoIdServiceActivity.RESULT_ERROR_CODE) val errorMsg = data?.getStringExtra(VideoIdServiceActivity.RESULT_ERROR_MESSAGE) // Handle error } } } ``` #### Proguard If you use Proguard (`minifyEnabled = true`), add the following rules to your proguard file: ``` -keep class eu.electronicid.sdk.modules.api.model.** { *; } -keep class eu.electronicid.sdk.domain.model.terms.** { *; } -keep class eu.electronicid.sdk.domain.model.videoid.event.** { *; } -keep class eu.electronicid.sdk.domain.model.errorreport.** { *; } -keep class eu.electronicid.sdk.domain.model.scan.** { *; } -keep class eu.electronicid.sdk.domain.model.Rectangle { *; } -keep class eu.electronicid.sdk.domain.model.Size { *; } -keep class eu.electronicid.sdk.h264encoder.X264Encoder { *; } -keep class eu.electronicid.sdk.yuvutils.YuvUtils { *; } -keep class eu.electronicid.sdk.videoid.model.** { *; } -keep class eu.electronicid.sdk.videoid.control.model.** { *; } -keep class eu.electronicid.sdk.videoid.control.communication.** { *; } -keep class eu.electronicid.sdk.videoid.adhoc.model.FrameCaptureStart { *; } -keep class eu.electronicid.sdk.videoid.webrtc.model.* { *; } -keep class org.webrtc.** { *; } -keep class eu.electronicid.sdk.discriminator.api.model.Bandwidth { *; } -keep class eu.electronicid.sdk.domain.model.Protocol { *; } ``` #### Verifying system requirements The SDK provides a function to verify that the user's device meets all requirements, such as camera compatibility and network speed. ```kotlin CheckRequirements.getInstance(this).checkVideoID(endpoint) { result -> if (result.passed) { // Requirements are met. Proceed with VideoID. } else { // Minimum requirements are not met. Fallback to an alternative. } } ``` ### iOS #### Import the SDK You can integrate the VideoID SDK using Swift Package Manager: In your Xcode project, go to `File > Add Packages` and enter the repository URL: `https://github.com/signicat/videoidskd-spm` #### Permissions You must add keys to your app's `Info.plist` file for camera and microphone access, including a description of why your app needs them. * `Privacy - Camera Usage Description` * `Privacy - Microphone Usage Description` #### Initialise and run the SDK (Swift) Present the `VideoIDSDKViewController` modally. You will need the `authorization` token obtained from your backend. ```swift // ... inside your ViewController func startVideoID() { let environment = VideoIDSDK.SDKEnvironment(url: yourEndpointURL, authorization: authorizationToken) let videoIDVC = VideoIDSDK.VideoIDSDKViewController( environment: environment, docType: 0, // Optional: Specify document type language: "en", // Optional: e.g., "es", "fr" idDefault: "", // Optional: Specify default country biometricConsent: true ) videoIDVC.modalPresentationStyle = .fullScreen videoIDVC.delegate = self self.present(videoIDVC, animated: true, completion: nil) } // MARK: - VideoIDDelegate extension ViewController: VideoIDDelegate { func onComplete(videoID: String) { // Process successful verification print("VideoID: \(videoID)") } func onError(_ error: VideoIDSDK.VideoIDError) { // Handle error print("VideoID Error: \(error.localizedDescription)") } } ``` #### Verifying system requirements The iOS SDK also includes a function to verify system requirements before starting the flow. ```swift VideoIDSDK.CheckRequirements().check(url: self.endpoint, service: .videoID, eager: false) { (checkResult) in DispatchQueue.main.async { if checkResult.passed { // Proceed with VideoID } else { // Handle unmet requirements } } } ``` ## 4. Start verification Your server (backend) must request the Assure API to start performing the identity verification. To do this, you just call the [Start verification](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/startVerification) endpoint. No parameters are necessary. ## 5. Get result After VideoID has analysed the images/videos, VideoID will send a callback to Assure API with the result. :::tip Assure Events It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see [Assure Events](/docs/id-document-and-biometric-verification/services/callbacks/). ::: You can call the [Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess) endpoint to get the full information about the process. For result examples, see [Service Details for VideoID > Get process](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-videoid/service-details/#get-process). :::tip Download full result You can also get a zip file with the packaged process by calling the [Download full result](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getZipFile) endpoint. ::: --- ## Service details for VideoID This section goes more into detail about some useful endpoints when integrating with VideoID: - [Start capture flow](#start-capture-flow) - [Get process](#get-process) - [Download full result](#download-full-result) ## Start capture flow ### Capture SDK The `"sdk":"capture"` option is not available for VideoID. However, you can use the VideoID native SDKs. To get help with this, please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### Signicat VideoID provider-specific configuration The Capture configuration includes specific configuration fields when using the _VideoID native SDK_. This configuration applies when the `sdk` field in the "Start capture flow" request is set to `native` and provider to `signicatvideoid`. For more details, see the `eidConfig` element in the API Reference for either [Create](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/setConfiguration_1) or [Update capture configuration](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/updateConfiguration_1). ## Get process This section describes the final result `status` that you receive in the [Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess) response for VideoID. ### Final result status VideoID returns information about whether the verification was accepted, rejected, inconclusive or failed. Assure API simply maps those values directly to the process' final status. Reasons for the process to be rejected is part of the response. VideoID responses will always have an `ocr` element for all process types (`substantial`, `substantialFullyAuto` and `high`). `high` process types (where an agent will review the process) has an additional `manualApproval` element. :::CustomTable{columnWidths="13% 13% 13% 13% 48%" minTableSize="850px"} | **processType** | **accepted** | **inconclusive** | **rejected** | | -------------------- | ------------------ | ------------------- | ------------------------------------- | | `substantial` | All automatic security checks (`ocr`) passed and all visual features were automatically detected. | All automatic security checks (`ocr`) passed. However, one or more visual features were not automatically detected and/or `similarityScore` is not `high`. | One or more automatic security checks (`ocr`) did not pass. | | `substantialFullyAuto` | All automatic security checks (`ocr`) passed | N/A | One or more automatic security checks (`ocr`) did not pass and/or `similarityScore` is not `high`. | | `high` | All security checks passed both by the automated engine (`ocr`) and the manual review by the human agent (`manualApproval`). | N/A | One or more manual security checks (`manualApproval`) did not pass. | ::: See example responses below for each process type: - [substantial](#substantial) - [substantialFullyAuto](#substantialfullyauto) - [high](#substantialfullyauto) ### substantial #### accepted Here is a response example of a VideoID Substantial process that was `accepted`: ```json { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "provider": "signicatvideoid", "processType": "substantial", "status": "accepted", "providerSpecific": { "ocr": { "similarityScore": "high", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 84, "y": 28, "width": 248, "height": 32 }, "side": "data" }, { "name": "OVI 2", "found": true, "bbox": { "x": 596, "y": 44, "width": 32, "height": 24 }, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 402, "y": 273, "width": 217, "height": 60 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 32, "y": 168, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": true, "bbox": { "x": 12, "y": 44, "width": 72, "height": 80 }, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2030-07-08", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" } }, } ``` For field descriptions, see the [Open API documentation > Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess). #### rejected The process gets the `rejected` status if one or more security checks are not valid. In this example, the reason is that the document has expired: ```json {15} { "processId": "1cc14545-0396-4cbe-8501-8f2461a91dfe", "createdAt": "2021-06-09T10:37:10Z", "updatedAt": "2021-06-09T10:38:04Z", "provider": "signicatvideoid", "processType": "substantial", "status": "rejected", "providerSpecific": { "ocr": { "features": [ { ... }, ... ], "securityChecks": { "nonExpired": { "valid": false }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "sidesMatch": { "valid": true }, "notBWCopy": { "valid": true } }, "socialSecurityNumber": "11926318740", "healthNumber": "1234567890", "taxNumber": "199693803", "similarityScore": "high", "livenessDetected": "true", "documentNumber": "1234567890", "dateOfExpiry": "2030-07-08", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "identityCard", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" } }, } ``` For field descriptions, see the [Open API documentation > Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess). #### inconclusive A process gets the `inconclusive` status in the following cases: - When the `similarityScore` value in the OCR analysis is other than `high` (see description of possible values for similarityScore under [API Reference > Get process > providerSpecific > ocr](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess)) - When one or more `features` are not "found", for example, if the end-user covers a visual element on the ID document while taking a photo of it. If you get an `inconclusive` status, you should inspect the process response to find the reason. In this example the status is inconclusive since _both_ `similarityScore` is too low (`verylow`) and two features are missing (`OVI 1` and `OVI 2` = `false`). ```json {7,23,50} { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "provider": "signicatvideoid", "processType": "substantial", "status": "inconclusive", "providerSpecific": { "ocr": { "similarityScore": "verylow", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 85, "y": 37, "width": 249, "height": 33 }, "side": "data" }, { "name": "OVI 2", "found": false, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 392, "y": 281, "width": 202, "height": 65 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 44, "y": 178, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": false, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2030-07-08", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" } }, } ``` #### failed A process gets the `failed` status if an error prevented the verification from completing. Examples could be that the microphone access is denied by the end-user or that the process times out due to inactivity on the end-user side (usually after 3 minutes). This is a response example of a VideoID process that `failed`: ```json {11} { "status": "failed", "processId": "4644c061-e229-449a-b4db-643c7403bbdc", "provider": "signicatvideoid", "processType": "substantial", "createdAt": "2021-04-15T08:25:04Z", "updatedAt": "2021-04-15T08:28:57Z", "failReason": { "id": "8ea0e55f-385f-47b7-a401-ef1db467a625", "type": "InactiveUser.Aborted", "message": "There has been no interaction with the video" } } ``` In this case, you can find more information about why it failed in the `failReason` object (see the [Errors](#errors) section). ### substantialFullyAuto #### accepted Here is a response example of a VideoID SubstantialFullyAuto process that was `accepted`: :::note Note In this case, even though the “OVI 1” visual feature was not found in the document, it is still accepted. ::: ```json { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "provider": "signicatvideoid", "processType": "substantialFullyAuto", "status": "accepted", "providerSpecific": { "ocr": { "similarityScore": "high", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 85, "y": 37, "width": 249, "height": 33 }, "side": "data" }, { "name": "OVI 2", "found": true, "bbox": { "x": 596, "y": 44, "width": 32, "height": 24 }, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 392, "y": 281, "width": 202, "height": 65 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 44, "y": 178, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": false, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2025-10-05", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" } } } ``` #### rejected The process gets the `rejected` status if one or more security checks are not valid or if the `similarityScore` is other than `high`. In this example, the `similarityScore` (between the picture in the ID document and the selfie) is `low`: ```json { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "provider": "signicatvideoid", "processType": "substantialFullyAuto", "status": "rejected", "providerSpecific": { "ocr": { "similarityScore": "low", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 84, "y": 28, "width": 248, "height": 32 }, "side": "data" }, { "name": "OVI 2", "found": true, "bbox": { "x": 596, "y": 44, "width": 32, "height": 24 }, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 402, "y": 273, "width": 217, "height": 60 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 32, "y": 168, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": true, "bbox": { "x": 12, "y": 44, "width": 72, "height": 80 }, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2025-10-05", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" } }, } ``` #### failed A process gets the `failed` status if an error prevented the verification from completing. Examples could be that the microphone access is denied by the end-user or that the process times out due to inactivity on the end-user side (usually after 3 minutes). This is a response example of a VideoID process that `failed`: ```json {11} { "status": "failed", "processId": "4644c061-e229-449a-b4db-643c7403bbdc", "provider": "signicatvideoid", "processType": "substantialFullyAuto", "createdAt": "2021-04-15T08:25:04Z", "updatedAt": "2021-04-15T08:28:57Z", "failReason": { "id": "8ea0e55f-385f-47b7-a401-ef1db467a625", "type": "InactiveUser.Aborted", "message": "There has been no interaction with the video" } } ``` In this case, you can find more information about why it failed in the `failReason` object (see the [Errors](#errors) section). ### high #### accepted Here is a response example of a VideoID High process that was `accepted`: ```json { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "processType": "high", "provider": "signicatvideoid", "status": "accepted", "providerSpecific": { "ocr": { "similarityScore": "high", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 84, "y": 28, "width": 248, "height": 32 }, "side": "data" }, { "name": "OVI 2", "found": true, "bbox": { "x": 596, "y": 44, "width": 32, "height": 24 }, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 402, "y": 273, "width": 217, "height": 60 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 32, "y": 168, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": true, "bbox": { "x": 12, "y": 44, "width": 72, "height": 80 }, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2025-10-05", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" }, "manualApproval": { "duration": "106", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "dateOfExpiry": "2025-10-13", "gender": "F", "nationality": "PRT", "documentNumber": "1234567890", "issuingCountry": "PRT", "dateOfBirth": "2002-04-29", "personalIdentificationNumber": "FANTASYBANK1234567890", "videoId": "dd56c701-9ad2-44c0-ab05-864cc46c7d69", "verificationId": "6b19d497-e024-4b9c-aade-e6e370b59670", "verifierId": "331971b7-4302-4cba-b5ea-4aec176f07d6", "verificationDate": "2025-04-01T08:29:53Z", "rAuthorityId": "fc6c2d52-b90a-4bb7-93e9-8fe020ae9da8" } } } ``` #### rejected The process gets the `rejected` status if one or more security checks are not valid. In this example, a support agent has rejected the identity verification in the manual approval step ("No evidence of a legal-looking identity document is evident."): ```json { "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3", "createdAt": "2021-06-09T10:04:42Z", "updatedAt": "2021-06-09T10:05:41Z", "processType": "high", "provider": "signicatvideoid", "status": "rejected", "providerSpecific": { "ocr": { "similarityScore": "high", "livenessDetected": "true", "features": [ { "name": "Header", "found": true, "bbox": { "x": 84, "y": 28, "width": 248, "height": 32 }, "side": "data" }, { "name": "OVI 2", "found": true, "bbox": { "x": 596, "y": 44, "width": 32, "height": 24 }, "side": "data" }, { "name": "Signature", "found": true, "bbox": { "x": 402, "y": 273, "width": 217, "height": 60 }, "side": "data" }, { "name": "Photo", "found": true, "bbox": { "x": 32, "y": 168, "width": 141, "height": 141 }, "side": "data" }, { "name": "OVI 1", "found": true, "bbox": { "x": 12, "y": 44, "width": 72, "height": 80 }, "side": "data" } ], "securityChecks": { "nonExpired": { "valid": true }, "notUnderage": { "valid": true }, "dataIntegrity": { "valid": true }, "livenessDetected": { "valid": true }, "notFaceSpoofing": { "valid": true }, "notBWCopy": { "valid": true } }, "documentNumber": "1234567890", "dateOfExpiry": "2025-10-05", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "documentType": "passport", "dateOfBirth": "2002-04-29", "gender": "F", "nationality": "PRT", "personalIdentificationNumber": "FANTASYBANK1234567890", "issuingCountry": "PRT" }, "manualApproval": { "duration": "106", "firstName": "MARIA PAULA", "lastName": "SANTOS MENDES", "dateOfExpiry": "2025-10-13", "gender": "F", "nationality": "PRT", "documentNumber": "1234567890", "issuingCountry": "PRT", "dateOfBirth": "2002-04-29", "personalIdentificationNumber": "FANTASYBANK1234567890", "rejectionReasons": [ { "type": "Document.Aspect", "message": "No evidence of a legal-looking identity document is evident." } ], "videoId": "dd56c701-9ad2-44c0-ab05-864cc46c7d69", "verificationId": "6b19d497-e024-4b9c-aade-e6e370b59670", "verifierId": "331971b7-4302-4cba-b5ea-4aec176f07d6", "verificationDate": "2025-04-01T08:29:53Z", "rAuthorityId": "fc6c2d52-b90a-4bb7-93e9-8fe020ae9da8" } } } ``` #### failed A process gets the `failed` status if an error prevented the verification from completing. Examples could be that the microphone access is denied by the end-user or that the process times out due to inactivity on the end-user side (usually after 3 minutes). This is a response example of a VideoID process that `failed`: ```json {11} { "status": "failed", "processId": "4644c061-e229-449a-b4db-643c7403bbdc", "provider": "signicatvideoid", "processType": "high", "createdAt": "2021-04-15T08:25:04Z", "updatedAt": "2021-04-15T08:28:57Z", "failReason": { "id": "8ea0e55f-385f-47b7-a401-ef1db467a625", "type": "InactiveUser.Aborted", "message": "There has been no interaction with the video" } } ``` In this case, you can find more information about why it failed in the `failReason` object (see the [Errors](#errors) section). ## Download full result In the [Get process response](#accepted), you get the results for VideoID in the provider-specific area (for example `similarityScore`). For full information as obtained from the provider, use the [Download full result](/docs/id-document-and-biometric-verification/services/download-full-result.mdx) service. This service returns a zip file containing data and media files about the verification. You can always get a zip file for VideoID processes that have been [completed with success](/docs/id-document-and-biometric-verification/services/process/#final). ### Data files #### ocr.json This "raw" file contains all information about the OCR capture and automatic verification performed by VideoID. #### manual_approval.json This "raw" file contains all information about the manual verification performed by the support agent. ### Media files :::CustomTable{columnWidths="33% 33% 33%"} | Type | File name/format | Comment | | :------ | :----------------- | :---------------------------------------------------------- | | front | front.jpeg | | | back | back.jpeg | Only retrieved if the ID document has a backside. | | selfie | selfie.jpeg | | | portrait | portrait.jpeg| | | video | video.mp4 | | ::: ## Errors Every time a VideoID process fails (is set to the `failed` status), error information is returned in the `failReason` object. This example shows a VideoID API user error with `Liveness.NotDetected` as reason: ```json {6} { "processId": "3e5f41ea-8b23-40ed-a8ac-f4d57d6cd4b2", "provider": "signicatvideoid", "processType": "substantial", "status": "failed", "failReason": { "id": "6c3bb734-34a1-4979-8a5b-14a91853cadb", "date": 1745491701000, "reason": "Liveness.NotDetected", "category": "User.Error" }, "createdAt": "2024-09-19T14:39:42Z", "updatedAt": "2024-09-19T14:40:16Z" } ``` Most of the errors will come from the VideoID API and contain "ID", "date", "reason" and "category". Other errors may come from the VideoID Web SDK or from Assure Capture service, and have a different structure. However, they will always contain information about what made the process fail. The possible cases for those errors are listed below, categorised into which part of the system they come from: - [VideoID API](#videoid-api) - [VideoID Web SDK](#videoid-web-sdk) - [Assure Capture](#assure-capture) ### VideoID API The following sub-sections list possible errors per error category for the VideoID API: - [Integration errors](#integration-errors) - [Camera errors](#camera-errors) - [Microphone errors](#microphone-errors) - [Network errors](#network-errors) - [Environment errors](#environment-errors) - [Document errors](#document-errors) - [User errors](#user-errors) - [Agent errors](#agent-errors) - [Verification errors](#verification-errors) - [Service errors](#service-errors) :::note Descriptions The below descriptions are not shown to the users in the UI. They are added here to help you understand the error and potentially give some advice to the user. ::: #### Integration errors The `Integration.Error` category contains errors caused by a faulty integration of VideoID. This should ideally never happen in a production environment, as these errors should be eliminated during the integration process. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Authorization.Invalid | Authorisation is not valid. | | Authorization.Reused | A previous authorisation cannot be reused. | | Browser.NotSupported | Browser is not supported, try from another browser. | | Device.NotSupported | Device is not supported, try from another device. | | Https.Required | VideoID must run under a secure protocol (https). | | IdType.Invalid | Document type is not valid. | | IdType.Unauthorized | IdType unauthorised. | | IdType.NotSupportedInWebBrowser | This identity document type is not supported in a web browser. | | VideoID.NotSupported | VideoID is not supported (WebRTC not available). | | Sdk.Exception | An unhandled exception occurred at the SDK level. Only applies to Android and iOS SDKs. | ::: #### Camera errors The `Camera.Error` category shows errors related to the device camera, for example `Camera.NotFound`. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Camera.NotFound | No camera is detected. | | CameraPermission.Denied | Camera access is denied. | | Camera.Unavailable | Camera is not available. Ensure it is not being used by another application. | | CameraResolution.TooLow | Camera resolution is too low. Try from another device with a better resolution. | | CameraRequirements.NotSatisfied | Camera does not meet the required specifications. | | Image.Blurred | Camera does not have the required image definitions. Try from another device. | ::: Apart from these specific camera errors, mobile SDKs can also return a generic `Permission.Denied` error (see the [User.Error](#user-errors) section). #### Microphone errors The `Microphone.Error` category contains errors related to the device microphone, for example `Microphone.NotFound`. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Microphone.NotFound | No microphone is detected. | | MicrophonePermission.Denied | Microphone access is denied. | ::: Apart from these specific microphone errors, mobile SDKs can also return a generic `Permission.Denied` error (see the [User.Error](#user-errors) section). #### Network errors The `Network.Error` category contains errors caused by internet connection problems, for example, `Connection.Lost`. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | WebRTC.NotAvailable | VideoID is not supported (WebRTC not available). | | Recording.Error | Network error during the video recording. Try again. | | Bandwidth.TooLow | Connection is too slow or unstable. Try from another network. | | Connection.Lost | Connection to server is lost. | | Connection.Error | Server connection error. Try again from another device or network. | | Connection.Unstable | Connection too unstable. Try from another network. | | Connection.Error | Server connection error. Try again from another device or network. | | RTCConnection.Lost | Connection to the server is lost. | | RTCConnection.Error | Network error during the WebRTC call. | | RTCConnection.NotAvailable | WebRTC service is not available. | | AgentRecording.Error | Network error during the recording of the agent’s video. Try again. | | AgentBandwidth.TooLow | Agent’s connection is too slow. Try again. | | AgentConnection.Lost | Connection to the agent is lost. | | AgentConnection.Error | Agent connection error. Try again. | | AgentConnection.Unstable | Agent’s connection is too unstable. Try again. | | AgentRTCConnection.Lost | Connection to agent lost. Try again. | | AgentRTCConnection.Error | Error during the agent call. Try again. | | AgentRTCConnection.NotAvailable | Agent is not available. Try again. | ::: #### Environment errors The `Environment.Error` category contains errors that happen because of bad lighting environments. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Luminance.TooLow | Lighting level is too low. Try from another place with better lighting. | | Luminance.TooHigh | Lighting level is too high. Try from another place with less lighting. | ::: #### Document errors The `Document.Error` category contains errors caused by the end-user using an invalid or illegible identity document, for example `DocumentSides.Mismatch`. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Document.NotAllowed | Identity document is not allowed. | | DocumentSides.Mismatch | The front and back of the identity document do not match. | | DocumentSidesMatch.NotPossible | The correspondence between the front and back of the identity document could not be verified. Try from another device with better image quality. | | Document.Illegible | The identity document could not be scanned. Try from another device with better image quality. | | Document.WrongSide | The wrong side of the identity document has been shown. Repeat the process by following the instructions. | | Document.Glared | Identity document could not be scanned. Try again avoiding glares over the document. | | Document.Expired | Identity document has expired. | | Document.Tampered | Tampered/Illegitimate document. | | Barcode.Illegible | Identity document could not be scanned. Try from another device with better image quality. | | Barcode.NotDetected | Barcode is not detected. Try from another device with better image quality. | | Hologram.NotDetected | Hologram is not detected in the identity document. | | Surface.NotReflective | The identity document was expected to have a reflective surface. | | BWCopy.Detected | It seems that a copy of the identity document is used. Try again using the original document or in another place with better lighting. | | Photo.NotDetected | No photograph is detected in the identity document. | ::: #### User errors The `User.Error` category contains errors caused by the user, for example, `User.Inactive`. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | MaxLength.Exceeded | Video has exceeded the maximum duration. | | User.Aborted | User has left this video session. | | InactiveUser.Aborted | There has been no interaction in the video. | | Liveness.NotDetected | Liveness could not be detected. Repeat the process by following the instructions. | | FaceSpoofing.Detected | Possible fraud is detected. | | FacesMismatch.Detected | Face in selfie and identity document does not match. | | FaceScanDiscontinuity.Detected | Face scan is unconvincing. Make sure that the process is carried out continuously by a person. | | MultipleFaces.Detected | More than one person is detected. Make sure only the owner of the identity document is present during the identification. | | Pose.NotFacingFront | Face not facing front. | | Captcha.Invalid | The captcha could not be validated. | | SmileID.NotValidated | Face could not be validated. | | User.Underage | User is under the adult age (18). Adult age is required. | | Permission.Denied | Some of the required permissions were not granted. | ::: #### Agent errors The `Agent.Error` category contains errors caused by the agent. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | Agent.Aborted | Agent has left this video session. | | NoAgent.Available | No agents are available. Try again later. | ::: #### Verification errors The `Verification.Error` category contains errors occurred during the manual verification process. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | VideoID.Rejected | Video rejected by the agent. | ::: #### Service errors The `Service.Error` category contains errors caused by the VideoID service. :::CustomTable{columnWidths="40% 60%"} | Reason | Description | | ------------------------------- | -------------------------------------------------------------------- | | VideoID.Error | An error has occurred. | | ApiCall.Error | An API call error has occurred. | | Instance.Down | An error has occurred on the server where VideoID was running. | ::: ### VideoID Web SDK :::CustomTable{columnWidths="50% 50%"} | Error message | Description | | -------------------------------------- | --------------------------------------------------------------- | | `{`  `"type": "system_requirements",`  `"message": "The following requirements were not met: { possible values: os, camera, microphone, bandwidth }. Full checks: { here goes a JSON object from VideoID checkRequirements }"``}`| This happens when any of the minimum requirements for the VideoID SDK are not met regarding OS, minimum bandwidth or access to camera and microphone. You can decide to make these requirements not mandatory by using [Update Capture Configuration](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/updateConfiguration_1) > `signicatvideoidConfig` > `minRequirementsMandatory`. The network connectivity check is not enabled by default. You can enable it by using [Update Capture Configuration](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/updateConfiguration_1) > `signicatvideoidConfig` > `checkRequirements`. | ::: ### Assure Capture :::CustomTable{columnWidths="50% 50%"} | Error message | Description | | -------------------------------------- | --------------------------------------------------------------- | | `{`  `"Video ID SDK timeout",`  `"message": "VideoID SDK failed to load within 8 seconds"``}`| This happens when the VideoID web SDK fails loading within 8 seconds. You can configure this value using [Update Capture Configuration](/apis/id-document-and-biometric-verification/#tag/Capture/operation/updateConfiguration_1) > `signicatvideoidConfig` > `sdkLoadTimeout`. | | `{`  `"message": "Couldn't get authorization from create process."``}`| This happens if Assure is not able to get an authorization from VideoID. | ::: --- ## Quick start guides This section provides quick start guides to setting up identity verification through the Assure API and the Identity Proofing API. * [**Assure API integration**](/docs/id-document-and-biometric-verification/assure-api/): Learn how to integrate with different eIDV providers like PictureID, ReadID, VideoID, Onfido and WebID through the Assure API. * [**Identity Proofing API integration**](/docs/id-document-and-biometric-verification/idproofing-api/): Learn how to integrate with ReadID and VideoID combined through the Identity Proofing API. :::tip ReadID native APIs In addition, you can also integrate towards ReadID through its native APIs. See the separate [ReadID](/docs/readid/) product documentation. ::: --- ## Quick start guide(Quick-start-guides) # Quick start guide Learn how to get started quickly with different eIDV services like PictureID, ReadID, VideoID, Onfido and WebID through the Assure API. This quick start guide shows you how to: 1. Get started with Signicat. 2. Get access to the Assure API. 3. Get started with our Postman collection to try out the Assure API. :::tip Reading tips If you want to read more before starting the integration, we recommend the following: - [Key concepts in the Assure API](/docs/id-document-and-biometric-verification/assure-api/key-concepts.mdx) to get an introduction to the main components in the Assure API. - The [API Reference](/apis/id-document-and-biometric-verification/) to get familiar with available endpoints. ::: ## Set up an API integration Setting up an API integration is the most flexible way of testing Signicat Assure. You can use your preferred IDE, Framework, Postman, etc. using credentials provided by Signicat. ### Initial preparations If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::warning Sandbox accounts When testing the integration in your default sandbox account (created automatically on sign-up), it is recommended to use dummy data. If you plan to go live or prefer not to share data, you can request your own dedicated sandbox account. This will ensure data privacy and isolation for your testing needs. Then please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ### Get client credentials To access the Assure API, you must use client credentials (client ID and secret) provided by Signicat. To learn how to obtain your own client credentials, see the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). #### Add product permission to Assure API Ensure your API client has the right permissions to the Assure API. Only an administrator in your organisation can add this permission (see [Managing roles and permissions](/docs/dashboard/access-management/managing-roles-and-permissions.mdx)). - Your administrator sets the permissions on the API client **Permissions** tab, by selecting **Manage product access** and the **Assure API** checkbox. Once your administrator has enabled the product permission to the Assure API, it should look like this: Add permissions In this example screen, the Permissions tab is greyed out, which means this example user has read-only access. #### Access to the eIDV providers After you have obtained your own client credentials, access to the [eIDV providers](/docs/id-document-and-biometric-verification/provider-specific-integrations/) is enabled automatically for **sandbox accounts**. Testing with sandbox accounts means that the providers will run in test mode. Be aware that some providers (for example Onfido) might return mock responses in test mode. To enable access to the providers for your **production accounts**, you need to contact an [onboarding manager](https://www.signicat.com/contact/contact-sales). ### Obtain an access token Use the [above](#get-client-credentials) client credentials to obtain an access token. :::info Want to learn more? To learn how to do this, see the [Obtain an access token](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx#4-obtain-an-access-token) section in the **Connect to Signicat APIs** quick start guide. ::: Example request: ```curl curl --location 'https://api.signicat.com/auth/open/connect/token' \ --header 'Authorization: Basic c2FuZGJveC1ncmF5LWdhcmRlbi02NDk6Q2U3NXVKWVpTa0hSTW1mYWJpTlBYejFVSkxNWDB1QmV3WmdoaVBycGZLNmpDWW0z' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=signicat-api' ``` Example response: ```json { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gtc2lnbmluZy1rZXktZmM4NDg1MWQ2NDczYmQ0ZDkyZmYwN2Q2MGJjYzhkMTQiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE2NzY1NjUyNjUsImV4cCI6MTY3NjU2NTg2NSwiaXNzIjoiaHR0cHM6Ly9hcGkuc2lnbmljYXQuZGV2L2F1dGgvb3BlbiIsImF1ZCI6Imh0dHBzOi8vYXBpLnNpZ25pY2F0LmRldiIsImNsaWVudF9pZCI6ImRldi1yaXBlLXNhaWwtOTc4IiwiYWNjb3VudF9pZCI6ImEtc2RnZS1TbzdOV05PNFpQZjVWaHg5aG9QSSIsImp0aSI6IkRBNTg1RTZGQjBBNUI5NjNEMDUzRTA1OUJCQ0I0MzY2IiwiaWF0IjoxNjc2NTY1MjY1LCJzYW5kYm94Ijp0cnVlLCJzY29wZSI6WyJzaWduaWNhdC1hcGkiXX0.NarwHuNQAUAXK0FDcoTZoHnZvJKKCs8u4B3Dvw0_xbR48MaEvnTtIh80em1k_90P4KJvbzp90IycnrsJxb64EvmCPcPl_kRlqY6bZTlO3fBSsqjJP3IIZBpX1n7rBWBeBB26Brlgdsrmi0PDmPjR7Hmjfgk2zkl-kR4d6ka0oYCSlIR43nNmNbtITqcay5gEkA5GpFeLH8ezIJkTzomeNswsNZs7tLOrz4Lks6BxcHIW3fBnY4go_y2UoQF6qxwZNVbQhRkEEtmPIYvezXGS9JMDOTjtBAxevyt2TsXpPx_IMhSRyHXAP12Q_3HG50-b0l97irEGhVf68N5Z-WgfOA", "expires_in": 600, "token_type": "Bearer", "scope": "signicat-api" } ``` When you have received the access token, you can use it in all requests to the Assure API (as the HTTP Bearer authentication header), for example: ```curl curl --location --request POST 'https://api.signicat.com/assure/dossiers' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gtc2lnbmluZy1rZXktZmM4NDg1MWQ2NDczYmQ0ZDkyZmYwN2Q2MGJjYzhkMTQiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE2NzY1NjUyNjUsImV4cCI6MTY3NjU2NTg2NSwiaXNzIjoiaHR0cHM6Ly9hcGkuc2lnbmljYXQuZGV2L2F1dGgvb3BlbiIsImF1ZCI6Imh0dHBzOi8vYXBpLnNpZ25pY2F0LmRldiIsImNsaWVudF9pZCI6ImRldi1yaXBlLXNhaWwtOTc4IiwiYWNjb3VudF9pZCI6ImEtc2RnZS1TbzdOV05PNFpQZjVWaHg5aG9QSSIsImp0aSI6IkRBNTg1RTZGQjBBNUI5NjNEMDUzRTA1OUJCQ0I0MzY2IiwiaWF0IjoxNjc2NTY1MjY1LCJzYW5kYm94Ijp0cnVlLCJzY29wZSI6WyJzaWduaWNhdC1hcGkiXX0.NarwHuNQAUAXK0FDcoTZoHnZvJKKCs8u4B3Dvw0_xbR48MaEvnTtIh80em1k_90P4KJvbzp90IycnrsJxb64EvmCPcPl_kRlqY6bZTlO3fBSsqjJP3IIZBpX1n7rBWBeBB26Brlgdsrmi0PDmPjR7Hmjfgk2zkl-kR4d6ka0oYCSlIR43nNmNbtITqcay5gEkA5GpFeLH8ezIJkTzomeNswsNZs7tLOrz4Lks6BxcHIW3fBnY4go_y2UoQF6qxwZNVbQhRkEEtmPIYvezXGS9JMDOTjtBAxevyt2TsXpPx_IMhSRyHXAP12Q_3HG50-b0l97irEGhVf68N5Z-WgfOA' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '' ``` ## Get started with Postman We have created a Postman collection that lets you try the Assure API. Select the button below to get the Signicat Assure API collection. [](https://documenter.getpostman.com/view/11919736/2sAYJ1jMNt) There are instructions at the start of the collection on how to use the collection template. The examples are using [Signicat PictureID](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-pictureid/) as provider. ## Next steps Dive deeper into the integration with the Assure API, using either of these flows: * [**Capture flow**](/docs/id-document-and-biometric-verification/assure-api/integration-flows#eidv-alternative-flow-web-only): Use the Capture flow as the quickest way to integrate (web only) * [**Generic flow**](/docs/id-document-and-biometric-verification/assure-api/integration-flows#eidv-generic-flow): Use the generic flow to integrate with the eIDV providers' SDKs (web and native mobile app) --- ## Quick start guide(3) # Quick start guide Learn how to get started quickly with identity document verification through the Identity Proofing API. :::tip Under development Signicat is developing a new API for identity verification, ID Proofing API, combining ReadID and VideoID into one solution. Documentation for this will follow later. For now, please use the [Assure API](/docs/id-document-and-biometric-verification/quick-start-guides/quick-start-guide-assure-api/). ::: --- ## Events You can request to be notified from the Assure API about the following events: - The [Process complete](#process-complete) event notifies you when a process is finished. - The [WebID zip file ready](#webid-zip-file-ready) event notifies when the WebID zip file is ready to be downloaded. To receive an event notification, you must subscribe to Assure Events in the Signicat Dashboard, as described below. ## Subscribe to Assure Events To subscribe to notifications from Assure Events: 1. Log into the [Dashboard](https://dashboard.signicat.com). 2. From the Dashboard home page, select **Events**, **Add subscriptions** and **Webhook** as subscription type. 3. Set up the webhook: - **Name** (mandatory): You can use any name to identify your subscription. - **Webhook** (mandatory): This is where you will receive the HTTP POST request. - **Secret** (optional but recommended): This is the secret for the message authentication. When selected, a secret token is automatically created for you. You can copy this secret token and use it to validate that the event payload is coming from Signicat. For more details, see [Validating payloads](/docs/dashboard/settings/events.mdx#validate-payloads). 4. In the "Listen to" list, choose **Selected events** > **Assure** and tick the events you want to subscribe to. :::tip To preview the JSON Schema presented in the body payload, hover over **Process complete** and select the **Preview** button. This will display the body payload format in the right pane. See screen images below. ::: 5. Select **Add** to add the selected event. It should now be displayed on the [**Subscriptions**](https://dashboard.signicat.com/events/subscriptions) page. ### Process complete If you have subscribed to the **Process complete** event, you will receive a notification each time an Assure process is [finished](/docs/id-document-and-biometric-verification/services/process.mdx#status), either successfully or not. Here is a preview of the JSON payload for the `process.complete` event: Process complete event `externalReference` is your reference to a `dossierId` in the Assure API. For more field descriptions, see the [Assure API Reference](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier). ### WebID zip file ready If you have subscribed to the **WebID zip file ready** event, you will receive a notification when the zip file is ready to be downloaded. For download details, see the [Download full result](/docs/id-document-and-biometric-verification/provider-specific-integrations/other-providers/webid/integration-guide-webid/#download-full-result) section. Here is a preview of the JSON payload for the `webid.zip.file.ready` event: WebID zip file ready `externalReference` is your reference to a `dossierId` in the Assure API. For more field descriptions, see the [Assure API reference](pathname:///apis/id-document-and-biometric-verification/#tag/Dossiers/operation/createDossier). ## Test subscription To check that you subscription is working: 1. On the [**Subscriptions**](https://dashboard.signicat.com/events/subscriptions) page, select the **Test events** button. This displays the **Test your events** page. 2. Create a mock event (see [example](#mock-example-for-process-complete) below) to test that your subscription and event handling code works. 3. From the drop-down menus, select your subscription and event type. The mock event will be sent to the selected subscription if it listens to the selected event type. 4. Select **Send**. You can now check that the notification has arrived to your defined webhook URL with the **200 OK** response status. ### Mock example for Process complete Here is an example of a mock event notification: Mock event notification :::warning Mock data The received data in this example is mocked. The real data for `dossierId` and `processId` must comply with the UUID format and status as described in the [Get process](/docs/id-document-and-biometric-verification/services/process.mdx#status) section. ::: ```json { "id": "mock-ae906f8462074aa8b3228881225609eb", "timestamp": "2024-04-11T10:46:30.6156082Z", "eventName": "process.complete", "sender": "assure-api", "eventData": { "dossierId": "3vEnkf81dvhNvUR5tIz0953mzenGpJFbdQVeWZw3KqfRps7Ecef5r3Uxu", "processId": "wKtjgVHLt2Ae5j2nX3rJz9P", "status": "m02N6Vl9ff3T6kyb86DZffTS3z5422iLaBCOAL3gQjiF8Rfa" }, "accountId": "a-sdge-ukFPCPQ2M1RjhbnRQop3", "expiresAt": "2024-04-11T10:47:00.6156082Z", "isMockEvent": true, "tags": [ "mock" ] } ``` ## Next step Dive deeper into how to set up events: * [**Events and webhooks**](/docs/dashboard/settings/events): Learn more about the Signicat Event service. --- ## Capture The Signicat Capture service provides the front-end user experience for capturing ID documents and selfies as part of the identity verification. This page details some of the most important endpoints in the Capture service. ## Start capture flow Use the [Start capture flow](pathname:///apis/id-document-and-biometric-verification/#tag/Capture/operation/createArtifact) endpoint to create an identity verification process in a web context. The Capture service helps capturing and uploading ID images from the identity verification process. :::tip Capture recommendations - **Recommended for web**: The Capture service encapsulates the providers' web SDKs. This means you do not have to integrate directly with those SDKs since they are already integrated into this service. Also, integrating with the Assure API using the Capture service ([eIDV alternative flow](/docs/id-document-and-biometric-verification/assure-api/integration-flows.mdx#eidv-alternative-flow-web-only)) is simpler than integrating using the provider SDKs directly ([eIDV generic flow](/docs/id-document-and-biometric-verification/assure-api/integration-flows.mdx#eidv-generic-flow)). - **Supported devices**: You can use the Capture service with all the providers that run in a web environment (currently Signicat VideoID, Signicat PictureID and Onfido). :::warning Capture in iframe For security reasons, Capture will only successfully load inside ` :::important PSD2 compliant This feature has been reviewed by a third party and is approved as a PSD2-compliant recovery method. ::: ### When to use account recovery Our account recovery feature is best fit for use cases when your end-user no longer has access to an active device. There are multiple reasons why an end-user may need to recover their account, such as: - If their device has been lost, broken or stolen. - If they have deleted your application (Android only). If your end-user still has access to their old device, then we recommend that you perform a recovery/activation of the new device by approving the operation on the old device instead. ## How does account recovery work? ### Prerequisites To be able to use our account recovery feature: - You need to configure account recovery in the application configuration on the Encap server. - Your end-user's device needs to have backup functionality enabled. :::note Note This is enabled by default. The supported backup providers are Google Cloud and Apple iCloud. ::: - **Optional**: If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure this feature in the application configuration on the Encap server. ### Basic flow for an account recovery 1. Your end-user adds account recovery in your app. 2. As a result, the recovery credentials are stored in the cloud backup. 3. At a later point in time, your end-user performs an account recovery using your app that has implemented our account recovery feature. :::note Note All account recovery-related SDK operations require a valid authorisation token. To find out how to obtain this, see the [Token authorisation](#token-authorisation) section. ::: ### Token authorisation When you are using our SDKs for account recovery, you need to provide a token to authorise the operation. - Authorisation tokens are issued by our server when performing certain SDK operations. - In these operations, you need to set what purpose you will use the token for. - The token is returned back to your app as a response. - This token is used to authorise the next account recovery operation after a successful registration or authentication. :::info What does this mean? For example, this makes it possible to implement a flow that both registers the end-user and adds account recovery for the registration, without an additional authentication. ::: #### Operations that require a token An authorisation token is required for the following recovery-related operations: - `addOrUpdateRecovery` - `deleteRecovery` #### Operations that can yield a token The server will issue an authorisation token for the following operations: - `finishActivation` - `finishAuthentication` - `finishAddOrUpdateRecovery` - `finishRecovery` - `finishDeleteRecovery` :::note Note You will obtain an authorisation token for `addOrUpdateRecovery` by setting the `TokenPurpose` to `addOrUpdateRecovery` in one of the operations specified above. ::: ### What does an account recovery look like? The account recovery can be secured using server-side face authentication or a recovery code. We recommend server-side face authentication as: - It is more user-friendly, with no recovery code to remember. - It enhances security by not having a recovery code which could be shared. :::info What could it look like for your end-users? To see what account recovery with face authentication could look like for your end-users, see our [Figma prototype](https://www.figma.com/proto/weohzGQQacg4K8ZOZ5p4Zt/MobileID?page-id=5616%3A10660&node-id=5616-16688&viewport=608%2C373%2C0.68&t=FRNEYvAlTbJvdzc4-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=5616%3A16688). You can either click the app's interface, or use the arrows below the phone. ::: #### Add account recovery using face authentication Account recovery using face authentication can be added to a registration that has activated face authentication as an authentication method. The most common approach is to add account recovery in the same flow as when the end-user activates face authentication, however, it is possible to add account recovery at a later stage as well. :::warning Important If the device deletes server-side face authentication as an authentication method, then the device will no longer be able to recover using face authentication. ::: ##### Flow 1: Add recovery during activation of face authentication To add account recovery in the same flow as activating face authentication: 1. Your app performs `startAddOrUpdate` and `finishAddOrUpdate` SDK operations to add server-side face authentication as a new authentication method. Simultaneously, your app obtains a valid authorisation token. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery during activation of face authentication actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant encap as Encap SCA user->>app: End-user starts process to add face authentication app->>encap: (SDK call) startAddOrUpdate encap-->>app: startAddOrUpdate response note over user, app: 1. End-user authenticates with biometrics or PIN 2. End-user performs a facial scan to add face authentication app->>encap: (SDK call) finishAddOrUpdate with TokenPurpose addOrUpdateRecovery encap-->>app: finishAddOrUpdate response with an authorisation token app->>encap: (SDK call) startAddOrUpdateRecovery with an authorisation token encap-->>app: startAddOrUpdateRecovery response app->>encap: (SDK call) finishAddOrUpdateRecovery encap-->>app: finishAddOrUpdateRecovery response encap->>sp: (Callback) new recovery added sp-->>encap: OK ``` ::: ##### Flow 2: Add recovery at a later stage To add account recovery at a later stage, when server-side face authentication has already been added as an authentication method for the device: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery at a later stage actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant encap as Encap SCA user->>app: End-user starts process to add account recovery app->>sp: Start authentication sp->>encap: POST /authentication with deviceId encap-->>sp: authentication response sp-->>app: OK app->>encap: (SDK call) startAuthentication encap-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>encap: (SDK call) finishAuthentication with TokenPurpose addOrUpdateRecovery encap-->>app: finishAuthentication response with an authorisation token app->>encap: (SDK call) startAddOrUpdateRecovery with an authorisation token encap-->>app: startAddOrUpdateRecovery response app->>encap: (SDK call) finishAddOrUpdateRecovery encap-->>app: finishAddOrUpdateRecovery response encap->>sp: (Callback) new recovery added sp-->>encap: OK ``` ::: #### Add account recovery using recovery code Account recovery using a recovery code can be added either during device registration, or to an existing registration. ##### Flow 1: Add recovery during a new registration To add account recovery during a new registration: 1. Your app obtains a valid authorisation token by performing a standard registration, using `startActivation` and `finishActivation` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery during a new registration actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant encap as Encap SCA user->>app: End-user opens app app->>sp: Start registration sp->>encap: POST /registrations encap-->>sp: activationCode sp-->>app: activationCode app->>encap: (SDK call) startActivation with activationCode encap-->>app: startActivation response note over user, app: End-user authenticates with biometrics or PIN app->>encap: (SDK call) finishActivation with TokenPurpose addOrUpdateRecovery encap-->>app: finishActivation response with an authorisation token app->>encap: (SDK call) startAddOrUpdateRecovery with an authorisation token encap-->>app: startAddOrUpdateRecovery response note over user, app: End-user selects a recovery code app->>encap: (SDK call) finishAddOrUpdateRecovery encap-->>app: finishAddOrUpdateRecovery response encap->>sp: (Callback) new recovery added sp-->>encap: OK ``` ::: ##### Flow 2: Add recovery at a later stage To add account recovery at a later stage to an existing registration: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery to an existing registration actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant encap as Encap SCA user->>app: End-user starts process to add account recovery app->>sp: Start authentication sp->>encap: POST /authentication with deviceId encap-->>sp: authentication response sp-->>app: OK app->>encap: (SDK call) startAuthentication encap-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>encap: (SDK call) finishAuthentication with TokenPurpose addOrUpdateRecovery encap-->>app: finishAuthentication response with an authorisation token app->>encap: (SDK call) startAddOrUpdateRecovery with an authorisation token encap-->>app: startAddOrUpdateRecovery response note over user, app: End-user selects a recovery code app->>encap: (SDK call) finishAddOrUpdateRecovery encap-->>app: finishAddOrUpdateRecovery response encap->>sp: (Callback) new recovery added sp-->>encap: OK ``` ::: #### Perform an account recovery To perform an account recovery, your app is restored with `startRecovery` and `finishRecovery` SDK operations, using data from the could backup. - The device ID (`deviceId`) that you use as a reference remains unchanged when your app is recovered. - Once a recovery has been performed, it cannot be used again. - To be able to recover again, your end-users need to add a new recovery on the device. - For recovery using face authentication, the face authentication method is automatically activated for the recovered device. :::details Sequence diagram ```mermaid sequenceDiagram title Perform account recovery actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant encap as Encap SCA user->>app: End-user starts recovery app->>encap: (SDK call) startRecovery encap-->>app: startRecovery response note over user, app: End-user either performs a face authentication or enters their recovery code app->>encap: (SDK call) finishRecovery encap-->>app: finishRecovery response encap->>sp: (callback) account recovery performed sp-->>encap: OK ``` ::: #### Manage account recovery Account recovery can be managed with operations to update or delete a recovery. ##### Update a recovery To update a recovery: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an update recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. ##### Delete a recovery To delete a recovery: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs a delete recovery flow using `startDeleteRecovery` and `finishDeleteRecovery` SDK operations. :::note Note Deleting a recover with face authentication does not delete the face authentication method. ::: ## How to implement account recovery To implement our account recovery feature, you need to: - [Configure the application configuration](#configure-the-application-configuration). - [Configure the mobile SDK](#configure-the-mobile-sdk). ### Configure the application configuration To use account recovery, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to perform recoveries. To do this, see [Update application configuration](https://demo.encapsecurity.com/pt/api/docs/index.html#_update_application_configuration) in the Encap REST API reference documentation. :::info Want to learn more? To learn more about the configurable properties, see the [Account recovery](/docs/mobile-identity/encap/server/manual/application-configuration.mdx#account-recovery) section in our **Application configuration** documentation. ::: :::warning Recovery using face authentication If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure server-side face authentication in the application configuration. To learn how to do this, see the configuration section in our [Face authentication](/docs/mobile-identity/encap/features/face-authentication/#configure-the-application-configuration) feature documentation. If you want to use a recovery code to protect the recovery backups, you can skip this step. ::: ### Configure the mobile SDK You must also configure the SDK for account recovery. To learn how to do this, read the platform-specific documentation using the buttons below: * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/account-recovery): Learn how to configure the Android SDK for account recovery * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/account-recovery): Learn how to configure the iOS SDK for account recovery ## API integration We provide endpoints for account recovery that allow you to optionally integrate with the Encap REST API. With these endpoints, you can carry out operations such as: - Determine if a device has set recovery credentials. - Retrieve information about recovery data and the recoveries performed from devices. - Override the defaults from the application configuration. ### Get general recovery information To get general information about all recoveries performed for an end-user's device, you can use the [Get device details](https://demo.encapsecurity.com/pt/api/docs/index.html#_get_device_details) endpoint. The list shows details of: - All active recoveries. - All performed recoveries. - All incomplete recoveries (where the user did not complete the recovery process). This endpoint also shows the state of the recovery lock described in the [Disable recovery for a specific device](#disable-recovery-for-a-specific-device) section below. ```http title="Get device details" GET /api/smart-device/v1/devices/{deviceId} ``` ### Get detailed information about a recovery To get detailed information about a specific recovery performed for an end-user's device, you can use the [Get perform recovery details](https://demo.encapsecurity.com/pt/api/docs/index.html#_get_perform_recovery_details) endpoint. You can use this endpoint to provide details from the recovery session, similar to enrolments and authentications. ```http title="Get perform recovery details" GET /api/smart-device/v1/perform-recovery-sessions/{session_uuid} ``` :::note Note You need the session ID (`session_uuid`) of the recovery to use this endpoint. - To get this, you can use the [Get sessions for device](https://demo.encapsecurity.com/pt/api/docs/index.html#deviceSessions) endpoint. ```http title="Get sessions for device" GET /api/smart-device/v1/device/{deviceId}/sessions ``` - If you have enabled callback, then the session ID will appear there. ::: ### Disable recovery for a specific device To disable recovery for a specific device, you can use the [Change recovery lock](https://demo.encapsecurity.com/pt/api/docs/index.html#_change_recovery_lock) endpoint. If recovery lock is enabled, then the device will be unable to perform any operations related to account recovery. :::tip Note Locking recovery prevents the device from adding and performing recoveries, even when recovery is enabled in the application configuration. ::: ```http title="Change recovery lock" PUT /api/smart-device/v1/devices/{deviceId}/recovery-lock ``` ### Disable recovery at enrolment To disable recovery at enrolment for a specific device, you can add an extra parameter to the [Start enrolment of device](https://demo.encapsecurity.com/pt/api/docs/index.html#_start_enrollment_of_device) call that you normally use: ```http title="Start enrolment of device" POST /api/smart-device/v1/enrollments ``` ```json title="Example: Extra parameter for enrolment call" { ... "recovery_lock": true ... } ``` --- ## App attestation ## About app attestation Our app attestation feature gives applications additional security, as it prevents third-party use of our APIs. Using this feature guarantees that our Encap server communicates with the correct app. Without app attestation, any mobile client with a valid application ID and end-to-end (E2E) public key can call and use our Encap mobile client APIs. This could allow a third party to create a malicious app, which can pose security and privacy risks. ## Understanding malicious API usage ### Normal use case In a normal use case, the customer's app interacts with the customer server and the Encap server through the Encap mobile SDK. Diagram showing normal API usage ### Malicious use case In a malicious use case, an attacker figures out how the Encap server and the customer backend API work, and uses them to create a malicious app. The Encap mobile client APIs are open, therefore any client with a valid application ID and E2E public key can call and use these APIs. Depending on the obfuscation and shielding of the apps, a skilled attacker with enough resources could pick out the necessary attributes to use the Encap APIs. All open APIs are vulnerable to some extent. Hiding all attributes to prevent this kind of abuse is not possible. Diagram showing malicious API usage Users of a malicious app activate the app against the customer's API; either willingly by filling out the activation details in the app, or unwillingly as a result of phishing. The activated user of the malicious app can then authenticate towards the customer's API and access customer data just as easily as if they were using the legitimate app. :::tip Note This is not a case of hacking the credentials, but social manipulation of the end-user and abuse of the customer's onboarding process. ::: Most of the processes that are abused in a malicious use case are outside the scope of the Encap solution because: - Proofing of end-users is handled entirely by the service provider. - The binding of an end-user's identity to an Encap credential is handled by the service provider. - The Encap solution only knows about registered devices, not the identity of the end-user. ### What risks can app attestation mitigate? App attestation can mitigate risks in situations of both malicious and non-malicious apps. #### Malicious apps In the case of malicious apps as described above, app attestation protects against risks such as: - Financial loss for the end-user. - Loss of privacy for the end-user. #### Non-malicious apps A non-malicious app is an app that attempts to misuse the Encap solution, but without malicious intent. App attestation protects against the risks that this can create, such as: - Unmanaged security and privacy risks. - Loss of control of customer communication for the service provider. :::tip Example of a non-malicious app For example, a consumer banking app wants to display customer bank statement data from another bank account by activating its own app against the Encap server, but without consent from the owning bank. This would be considered misuse of the Encap solution, which app attestation would protect against. ::: ## Mitigating malicious API usage with app attestation To prevent third-party use of our APIs and to enforce the use of legitimate apps with our own SDK, we have introduced two features for app attestation; Play Integrity for Android and App Attest for iOS. ### How does Play Integrity work? For Android devices, we make use of Play Integrity's Attestation API. This API is provided by Google as part of the Android platform, and gives your app additional security against threats such as device tampering and potentially harmful apps. Based on the results of the attestation, it is possible to deny access on rooted device and emulators. Play Integrity ensures: - The integrity of the device. - That the application is genuine. - That the application has been installed using Google Play. :::tip Encap SDK compatibility For Encap SDKs of version 3.17 or later, only Play Integrity is supported. ::: #### Basic flow for an attestation The Encap server sends a nonce to the client. The Android client calls the Google Play Integrity Attestation API and passes on the nonce. The Google server verifies that it is a known device and returns the Google-signed attestation. The app sends the attestation data back to the Encap server. The server verifies: That the attestation signature has not been tampered with. The timestamp, to make sure that not too much time has passed. That the nonce is the same as for the initial request. That the attestation is from the right app. The application hash. That the attestation is from a real device. The integrity of the device. If all checks pass on the server, the activation/authentication can continue. If not, then the resulting status is sent to the service provider. :::tip Learn more about Play Integrity You can find a full description of Play Integrity in the Android developer portal: - [Play Integrity API](https://developer.android.com/google/play/integrity/) ::: #### Risks - It is possible that some phones (such as models by Chinese brands) could fail the integrity test. - There is a risk that rooted devices will not pass the integrity test. This means that if someone has configured Shield to not crash but just warn, they will still fail the authentication. - There is a quota limit of 10,000 requests a day per API key. This limit can be [increased by Google on request](https://developer.android.com/google/play/integrity/overview). - The Google service could be down. ### How does App Attest work? For iOS devices, we make use of App Attest. This API is provided by Apple as part of the iOS platform, and gives your app a way to assert its validity by enforcing the use of trusted apps with genuine Encap SDKs. This means that the Encap server can more confidently provide access to sensitive resources. App Attest gives your app an equal or higher level of integrity assurance to the previously available Intermediate Push feature, without the need to rely on complex push infrastructure. You can find an overview of the service backing this feature in the [Apple developer documentation](https://developer.apple.com/documentation/devicecheck/validating-apps-that-connect-to-your-server). :::tip Available iOS versions Apple app attestation is only available for Apple devices running iOS 14 and later. ::: #### Basic flow for an attestation 1. The Encap server sends a nonce to the client. 2. The client generates a key in the Secure Enclave, and stores the key identifier (`keyID`). 3. The client attests the key by passing the `keyID` and the nonce to Device Check API. This results in a call to an Apple server, where an attestation object is returned. 4. The client sends the attestation object along with the `keyID` to the Encap server. 5. The Encap server parses and validates the attestation object. 6. If all checks pass on the server, then the activation/authentication can continue. If the checks do not pass, then the resulting status is sent to the service provider. :::tip Learn more about App Attest You can find a full description of App Attest in the Apple developer portal: - [Establishing your app's integrity](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity). ::: #### Risks - On a compromised system such as a jailbroken device with signing protection disabled, it is possible to get valid assertion objects from modified versions of the app. - The `attestKey` call on the client communicates with Apple servers, where the requests per second are rate limited. Therefore, it might not be possible to onboard all customers for a large user base directly. - [App extensions](https://developer.apple.com/app-extensions/) are not supported. This means that attestation will fail in an app extension. - The Apple App Attest service could be down. ## API integration ### Attestation result object The attestation result is provided in the REST response as the `attestation` object. To learn more about this, you can refer to the [Encap API reference documentation](https://demo.encapsecurity.com/pt/api/docs/index.html#attestation-object). The attestation object is: - A sub-object of the [device object](https://demo.encapsecurity.com/pt/api/docs/index.html#deviceObject). - A session object for [activation](https://demo.encapsecurity.com/pt/api/docs/index.html#enrollObject) (registration/enrolment). - A session object for [authentication](https://demo.encapsecurity.com/pt/api/docs/index.html#authObject). #### Response fields :::CustomTable | **Field** | **Type** | **Description** | | :-- | :-- | :-- | | `play_integrity_status` | | The Play Integrity attestation status for the device. | | `play_integrity_date` | | The date of when the Play Integrity attestation was performed. | | `app_attest_status` | | The App Attest attestation status for the device. | | `app_attest_date` | | The date of when the App Attest attestation was performed. | ::: **Example: Attestation result for device using Android Play Integrity** ```json "attestation" : { "play_integrity_status" : "VERIFIED", "play_integrity_date" : "2019-09-20T13:14:01.984UTC", } ``` **Example: Attestation result for device using iOS App Attest** ```json "attestation" : { "app_attest_status" : "VERIFIED", "app_attest_date" : "2019-09-20T13:14:01.984UTC" } ``` ### Failed operations due to attestation If the attestation mode is set to `OFF` or `OPTIONAL`, then the operation **will not fail** if the attestation verification fails. If the attestation mode is set to `REQUIRED`, then the operation **will fail** if the attestation verification fails. When this happens, the session will return a session status. See the **Session statuses** table under [3.1.4 The session status object](https://demo.encapsecurity.com/pt/api/docs/index.html#session-status-object) in the Encap API reference documentation for possible values. ## How to configure app attestation To use our app attestation feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). - [Configure additional tracking](#configure-additional-tracking). ### Configure the mobile SDK Learn how to configure the mobile SDK for app attestation. * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/app-attestation): Learn how to configure the Android SDK for app attestation * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/app-attestation): Learn how to configure the iOS SDK for app attestation ### Configure the application configuration Learn how to configure the application configuration for app attestation. #### Attestation modes The app attestation feature can be used in multiple modes: :::note OFF The `OFF` mode means that attestation is not performed. By default, attestation is turned `OFF`. ::: :::note OPTIONAL The `OPTIONAL` mode means that attestation is performed. If attestation fails, then the transaction will not fail, and a new attestation is performed on the next transaction. ::: :::note REQUIRED The `REQUIRED` mode means that attestation is performed. If attestation fails, then the transaction will fail and the device is locked. The device must perform a successful attestation before it can be used for future transactions. Attestation is triggered on new registrations, or the first authentication if the registration already exists. **Note**: Devices running versions of iOS older than iOS 14 will always fail if the mode is `REQUIRED`, due to requirements by the Apple App Attest API. ::: :::tip Our recommendation For an existing installation with devices already activated on previous versions of Encap, we recommend that you start out using the `OPTIONAL` mode. You can read more about the reasons for this in the [How to roll out app attestation](#how-to-roll-out-app-attestation) section. ::: #### Play Integrity (Android) ##### Setting the properties To enable Play Integrity, you need to set the following properties in the application configuration: :::CustomTable | **Property name** | **Description** | **Allowed values** | | :-- | :-- | :-- | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` | Determines whether Play Integrity attestation is performed, and how the request is handled. | `OFF`, `OPTIONAL`, `REQUIRED` | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_TIMEOUT` | The timeout (given in milliseconds) for a request made to Play Integrity google service. | From `1` to `MAXINT`. | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY` | Play Integrity attestation decryption key (base-64 string), used to decrypt the integrity token. | Base64 string from Google Play Console. | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY` | Play Integrity attestation verification key (base-64 string), used to validate the integrity token. | Base64 string from Google Play Console. | | `ATTESTATION_ANDROID_PACKAGE_NAME` | The APK package name. | String | ::: :::tip Mandatory configurations If `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` is set to `REQUIRED` or `OPTIONAL`, then all Play Integrity configurations defined in the table above are required. ::: ##### Play Integrity verdicts The table below illustrates Play Integrity verdicts: :::CustomTable{columnWidths="50% 50%"} | **Verdict** | **Value** | | :-- | :-- | | `deviceRecognitionVerdict` | `MEETS_DEVICE_INTEGRITY` | | `appRecognitionVerdict` | `PLAY_RECOGNIZED` | | `appLicensingVerdict` | `LICENSED` | ::: The result of the verdicts will dictate how the operation is handled, depending on what you have set the attestation mode to: - If the `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` is set to `REQUIRED`, then the server will only authorise an operation if the mobile device passes all of the verdicts. - If the `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` is set to `OPTIONAL`, then the same verdicts are performed. However, if the device fails any of the verdicts, the operation is still authorised. - If the `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` is set to `OFF`, then Play Integrity attestation is disabled. You can read more about integrity verdicts in the [Google developer documentation](https://developer.android.com/google/play/integrity/verdicts). ##### Obtaining the decryption and verification keys :::warning Warning You must set the following application configuration properties in order for the server to decrypt the token response from the Play Integrity API: - `ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY` - `ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY` Without these values, the server will return an error. ::: In order to perform the decryption and validation of the token sent from the application to the server, you need to set up the decryption key and validation key provided from the Google Play Console in the application configuration file. To do this: 1. Access your application in the Google Play Console. 2. In the left-side menu, select **App integrity**. 3. On the Play Integrity API header, click **Settings** on the right-hand side. 4. Under **Project configuration**, click **Link a Cloud project**. You can link an existing project that you already use, or you can create a new one. 5. Under **Class requests**, click **Edit** on the **Response encryption** field, then select **Manage and download my response encryption keys**. 6. Follow the instructions listed under **Show instructions** and upload the public key `.pem` file. Then click **Save changes**. 7. Go back to the previous view and press **Download keys**. 8. Download the keys, then use the private key generated in the previous step to obtain the values for `DECRYPTION_KEY` and `VERIFICATION_KEY`. 9. Update your application configuration with the keys obtained. #### App Attest (iOS) ##### Setting the properties To enable App attest, you need to set the following properties in the application configuration: :::CustomTable | **Property name** | **Description** | **Allowed values** | | :-- | :-- | :-- | | `ATTESTATION_IOS_APP_ATTEST_MODE` | Determines whether App Attest attestation is performed, and how the request is handled. | `OFF`, `OPTIONAL`, `REQUIRED` | | `ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT` | Determines the environment where an iOS app that uses app attestation validates itself. | `PRODUCTION`, `DEVELOPMENT` | | `ATTESTATION_IOS_APP_ATTEST_TIMEOUT` | The timeout (given in milliseconds) for a request made to App Attest service. | From `1` to `MAXINT`. | | `ATTESTATION_IOS_APP_ATTEST_APP_ID` | The iOS app ID which is a concatenation of a 10-digit team identifier, a period, and the app's `CFBundleIdentifier` value **Example**: `0123456789.com.company.myApp` | String | ::: :::tip Note If `ATTESTATION_IOS_APP_ATTEST_MODE` is set to `REQUIRED` or `OPTIONAL`, all other App Attest configurations defined in the table above are required. ::: ##### App attest environments You can set either of the following environments for the `ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT` added to your application configuration: - `PRODUCTION` is the App Attest production environment. Keys that you create in the production environment do not work in the sandbox environment. - `DEVELOPMENT` is the App Attest sandbox environment that you use to test a device without affecting its risk metrics. Keys that you create in the sandbox environment do not work in the production environment. ### Configure additional tracking To track failed attestations in logs, add the following in `logback.xml`: **Example: Log for Android Play Integrity** - For Encap server versions 3.18 and above: ```xml ``` - For Encap server versions below 3.18: ```xml ``` **Example: Log for Apple App Attest** - For Encap server versions 3.18 and above: ```xml ``` - For Encap server versions below 3.18: ```xml ``` ## How to roll out app attestation :::tip Availability - Apple App Attest is only available for devices running **iOS 14** and later. - Google Play Integrity is available for all supported Android devices. ::: ### New customers For a clean Encap installation (with the server and the client SDK on version 3.15 or later), we recommend that the attestation mode is configured as `REQUIRED` for both Android and iOS devices from the start. This means that all devices that register successfully have been verified to be real Android or iOS devices, activated on a specific Encap app. You can read more about ensuring that all registrations have a successful attestation in the [Reach full security](#reach-full-security) section. ### Existing customers For existing Encap installations, we recommend carrying out the configuration in steps to minimise the end-user support needed. 1. Upgrade the server and the client to version 3.15 or later. 2. Configure the clients to support attestation. 3. Set the attestation modes to `OPTIONAL`. Once this is enabled, all existing and new customers will trigger a Play Integrity or App Attest attestation on their next authentication or activation. - The transactions will work as normal, but you will now be able to see how many registrations are failing the attestation verification. - This can be tracked in the logs or in the REST response for the transaction, making it possible to see the reason for the failure. - You can then tweak the configuration, support end-users, and/or update your app to reach an acceptable level of successful attestations. 4. Set the attestation modes to `REQUIRED`. If an attestation fails in this mode, the transaction will now fail. You can read more about ensuring that all registrations have a successful attestation in the [Reach full security](#reach-full-security) section. ### Considerations These considerations apply to both new and existing installations of Encap. #### Play Integrity - We recommend that you start with the attestation mode set to `OPTIONAL`, to avoid potential attestation failures. - The default Play Integrity quota is 10,000 requests per day. If the daily activation load is higher than the quota, then the activation will fail. Therefore, the quota limit must be [increased by Google on request](https://developer.android.com/google/play/integrity/overview), to be greater than the daily activation load. - If this feature is enabled on an existing installation, then the Play Integrity attestation will be triggered on both the next authentication for all existing registrations and new activations. This needs to be considered when setting the Play Integrity quota. #### App Attest - We recommend that you start with the attestation mode set to `OPTIONAL`, to avoid potential attestation failures. - If the user base is large, the app may send many requests to the Apple App Attest service. In order to manage resources and avoid being rate limited, this feature could be introduced gradually. You can do this by using [App Store Version Phased Releases](https://developer.apple.com/documentation/appstoreconnectapi/app_store_version_phased_releases) to release app updates gradually to end-users, over a 7-day period. - Apple App Attest is only available for devices running iOS 14 and later, and requires Encap Client API 3.15 and later. ### Reach full security To ensure all registrations have a successful attestation when performing a transaction, you need to: - Set the attestation mode to `REQUIRED` (applies to Play Integrity and App Attest). - Set `MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID` to 3.17 for Play Integrity in the application configuration. This will force older clients to upgrade the app before they can use it again. - Set `MINIMUM_REQUIRED_ENCAP_API_VERSION_IOS` to 3.15 for App Attest in the application configuration. This will force older clients to upgrade the app before they can use it again. --- ## Device groups ## About device groups Our device groups feature allows end-users to share a single server-side FaceMap across multiple devices. This eliminates the need for end-users to re-activate the authentication method on each new device, simplifying the user experience and reducing onboarding friction. By linking an end-user's devices together, you can provide a more seamless and secure cross-device experience. ### When to use device groups The primary benefit of device groups currently is to enable a single server-side FaceMap to be shared across multiple devices. This means that your end-users can avoid going through the activation process for the authentication method on every new phone or tablet. If you are not using our face authentication feature (meaning that `DEVICE_SERVER_SIDE_FACE` is not an allowed authentication method in your application configuration), then you will not see any immediate functional benefits from using device groups currently. :::info Useful information Device groups lay the foundation for more powerful cross-device features in the future. ::: ## How to implement device groups To use device groups, you do not need to configure anything specific in your application configuration. However, you must ensure that all devices belong to the same application configuration. This is because a device group is constrained to a single application configuration. To experience the full benefit with dynamic activation of the `DEVICE_SERVER_SIDE_FACE` authentication method, then the devices need to be upgraded to SDK version 3.22 or later. To learn more about the expected behaviour between versions, see the table below: | **SDK version** | **Behaviour** | | :-- | :-- | | SDK version 3.22 or later | These devices can recognise and immediately use an existing FaceMap available in the group without needing to re-activate the face authentication method. | | SDK versions older than 3.22 | These devices are unaware of the device group and shared FaceMap. This means that they will need to activate face authentication again, even if a FaceMap already exists in the group. **Note**: Any face authentication activation performed by these older devices is added to the group and can be immediately used by other devices running SDK 3.22 or later. | ### Adding devices to a group A device group is identified by a unique `group_id`, which is a UUID. All devices in a group share this identifier. Devices can be added to a group in several ways: - **Implicit creation**: A device group is created implicitly when an end-user activates face authentication method `DEVICE_SERVER_SIDE_FACE` for the first time. This device then becomes the first member of this group. - **During registration**: By providing an existing `group_id` when starting a new registration. - **After registration**: By using the device group endpoints to link an existing device to a group. ### Dynamic activation on new devices When a new device running SDK version 3.22 or later is added to a device group with face authentication already activated, the `DEVICE_SERVER_SIDE_FACE` authentication method is dynamically activated on that device. This allows immediate use of face authentication without requiring the end-user to reactivate the face authentication method. ### Group lifecycle and cleanup The lifecycle of a device group is managed automatically: - **Implicit deletion**: If a device is removed from a group and it was the last device in that group, then the group and its associated FaceMap are implicitly deleted. - **No empty groups**: A group cannot exist without at least one associated device. This ensures that resources like FaceMaps are cleaned up when no longer needed. ## API integration We provide endpoints for device groups that allow you to integrate with the Encap REST API. With these endpoints, you can carry out operations such as: - Manage device groups. - Link devices to groups - List group details. - Manage the lifecycle of the group. ### Get group for a device To get information about the device group for a specific device, you can use the following endpoint. ```http title="Endpoint: Get group for a device" GET /api/smart-device/v1/devices/{deviceId}/group ``` ```json title="Example: Response" { "group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "ref": "/groups/a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` ### Create new group for a device To create a new device group and add the device to that group, you can use the following endpoint. :::note Note This operation is only possible if the device does not already have a group. ::: ```http title="Endpoint: Create new group for a device" POST /api/smart-device/v1/devices/{deviceId}/group ``` ```json title="Example: Request" { "group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` ### Update group for a device To update or set the device group for a device, you can use the following endpoint. :::tip Tip You can use this endpoint to move a device to a different group. ::: ```http title="Endpoint: Update group for a device" PUT /api/smart-device/v1/devices/{deviceId}/group ``` ```json title="Example: Request" { "group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` #### Remove device from a group To remove a device from its device group, you can use the following endpoint. :::note Note If this operation results in there being no devices left in the device group, then the device group and its associated FaceMap are implicitly deleted. ::: ```http title="Endpoint: Remove device from a group" DELETE /api/smart-device/v1/devices/{deviceId}/group ``` ### Get group details To get detailed information about a specific device group, you can use the following endpoint: :::note Note Detailed information includes: - The status of face authentication. - A list of devices in the device group. ::: ```http title="Endpoint: Get group details" GET /api/smart-device/v1/groups/{groupId} ``` ```json title="Example: Response" { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "server_side_face": { "status": "ACTIVE" }, "devices": [ { "device_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210", "current_client_api_version": "3.22.0" }, { "device_id": "01234567-89ab-cdef-0123-456789abcdef", "current_client_api_version": "3.22.0" } ] } ``` ### Start device registration with group To assign a device to a device group during the registration process, you can use the following endpoint. :::note Note This is possible because when you start a device registration, you have the option to provide an existing `group_id` to immediately link the new device to that device group. ::: ```http title="Endpoint: Start device registration with group" POST /api/smart-device/v1/registrations ``` ```json title="Example: Request" { // ... other device registration fields // Optionally assign device registration to an existing group: "group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` --- ## Device hash blocking ## About device hash blocking You can use our device hash blocking feature to block a physical device from activating or recovering on the Encap server. To do this, the device hash is blocklisted on the Encap server. This means that any activation or recovery attempt from that device is rejected, regardless of which end-user or registration is involved. :::info Comparison to device hash locking This feature is distinct from the [Device hash locking](/docs/mobile-identity/encap/features/device-hash-locking) feature, which locks existing registrations. Device hash blocking in comparison prevents new registrations from being created on the device at all. ::: ### Example use case A device is identified as compromised or fraudulent. By blocking its device hash, you prevent the device from being used to activate any new registrations or perform a recovery, even after deactivation of existing registrations. ## What is a device hash? A device hash is a SHA-256 hash of the unique hardware ID of a physical device. - For Android, the hardware ID is derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. - For iOS, the hardware ID is generated by the SDK using Apple's `CFUUIDCreate` function and stored in the end-user's iCloud Keychain. :::info Want to learn more? To learn more, see the device hash appendix for [Android](/docs/mobile-identity/encap/sdk-android/appendix/device-hash) and [iOS](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash). ::: ## How blocklisting works When a device hash is blocklisted, the Encap server enforces the block at the following points: :::CustomTable{tableName="Blocklist enforcement points" columnWidths="30% 70%"} | **Operation** | **Effect** | | :-- | :-- | | Finish activation | The activation is rejected. The session is set to `DEVICE_HASH_BLOCKLISTED`. | | Finish perform recovery | The recovery is rejected. The session is set to `DEVICE_HASH_BLOCKLISTED`. | ::: When a blocklisted device is blocked by the Encap server, the server sends an event callback for the operation with a `FAILED` status. This enables your platform to react immediately. :::tip What does this mean? For example, your platform could react by notifying your fraud or operations team. ::: ## Scoping The `applicationId` query parameter controls the scope of a blocklist entry: :::CustomTable{tableName="blocklist scoping" columnWidths="40% 60%"} | **Scenario** | **Behaviour** | | :-- | :-- | | The `applicationId` is provided. | The blocklist entry is scoped to that specific application. **Note**: This means that only activations and recoveries for that application are blocked. | | The `applicationId` is omitted. | The blocklist entry applies across all applications in your organisation. | ::: ## API integration We provide endpoints for blocklisting in the Encap REST API. With these endpoints, you can carry out operations such as: - Check if a device hash is blocklisted. - Add a device hash to the blocklist. - Remove a device hash from the blocklist. ### Check if a device hash is blocklisted You can use this endpoint to check if a device hash is blocklisted. - If the device hash is blocklisted, the operation returns `200 OK`. - If the device hash is not blocklisted, the operation returns `404 Not Found`. :::note Note - The `deviceHash` path parameter must be URL-safe Base64 encoded. - The `applicationId` query parameter is optional. ::: ```http title="Check if a device hash is blocklisted" GET /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId} ``` #### Example ```http title="Example: Request" GET /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp ``` ### Add a device hash to the blocklist You can use this endpoint to add a device hash to the blocklist. - If successful, the operation returns `204 No Content`. - If the `applicationId` is provided in the request and the device hash is already blocklisted for that application, the operation returns `409 Conflict`. - If the `applicationId` is omitted from the request, then device hash is blocklisted across all applications in the organisation that have an existing registration for this device. :::note Note - The `deviceHash` path parameter must be URL-safe Base64 encoded. - The `applicationId` query parameter is optional. ::: ```http title="Add a device hash to the blocklist" POST /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId} ``` #### Example ```http title="Example: Request" POST /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp ``` ### Remove a device hash from the blocklist You can use this endpoint to remove a device hash from the blocklist. - If successful, the operation returns `204 No Content`. - If the entry does not exist, the operation returns `404 Not Found`. :::note Note - The `deviceHash` path parameter must be URL-safe Base64 encoded. - The `applicationId` query parameter is optional. ::: ```http title="Remove a device hash from the blocklist" DELETE /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId} ``` #### Example ```http title="Example: Request" DELETE /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp ``` ### Blocklist response object When you retrieve device details using the **Get device** endpoint shown in the example below, the response includes a `blocklist` object if the device's hash is blocklisted. :::note Note The `blocklist` field is only present in the response when the device hash is blocklisted. ::: :::CustomTable{tableName="Blocklist response object fields" columnWidths="30% 20% 50%"} | **Field** | **Type** | **Description** | | :-- | :-- | :-- | | `blocklist.ref` | String | A URL reference to the blocklist entry, using URL-safe Base64 encoding of the device hash. | | `blocklist.device_hash` | String | The standard Base64-encoded device hash. | | `blocklist.created_at` | String | The timestamp when the blocklist entry was created, in ISO 8601 format. | ::: #### Example ```http title="Example: Request" GET /api/smart-device/v1/devices/{deviceId} ``` ```json title="Example: Response (blocklist object only)" { "blocklist": { "ref": "/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp", "device_hash": "wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=", "created_at": "2026-05-21T10:30:00.000Z" } } ``` --- ## Device hash locking ## About device hash locking One physical device can be tied to several registrations. For example, this could happen after an end-user has re-registered using the same device. You can use our device hash locking feature to get and lock all registrations tied to a particular device hash using a single operation. :::info Comparison to device hash blocking This feature is distinct from the [Device hash blocking](/docs/mobile-identity/encap/features/device-hash-blocking) feature, which prevents new registrations from being created on the device at all. Device hash locking in comparison locks existing registrations. ::: ### Example use case An end-user reports their device as stolen. Using the device hash, you can immediately lock all active registrations associated with that physical device, without needing to track down each individual device ID. ## What is a device hash? A device hash is a SHA-256 hash of the unique hardware ID of a physical device. - For Android, the hardware ID is derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. - For iOS, the hardware ID is generated by the SDK using Apple's `CFUUIDCreate` function and stored in the end-user's iCloud Keychain. :::info Want to learn more? To learn more, see the device hash appendix for [Android](/docs/mobile-identity/encap/sdk-android/appendix/device-hash) and [iOS](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash). ::: ## How locking works ### Platform behavior Depending on the mobile platform, the device hash behaves differently when an app is reinstalled on the same device: :::CustomTable{tableName="Overview of reinstall behaviour" columnWidths="25% 75%"} | **Platform** | **Description** | | :-- | :-- | | Android | The UUID may change, either: After a factory reset is performed. After the device is upgraded from a version prior to Android 8.0 to Android 8.0 or above, and the app is then reinstalled. | | iOS | The UUID persists across uninstall and reinstall cycles. It is only lost if a factory reset is performed on the device **without** restoring from a backup. | ::: ## Scoping The `applicationId` query parameter controls the scope of the operation: :::CustomTable{tableName="Operation scoping" columnWidths="40% 60%"} | **Scenario** | **Behaviour** | | :-- | :-- | | The `applicationId` is provided. | The operation is scoped to that specific application. **Note**: This means that only registrations for that application are returned or locked. | | The `applicationId` is omitted. | The operation applies across all applications in your organisation. | ::: ## API integration We provide endpoints for device hash management in the Encap REST API. With these endpoints, you can carry out operations such as: - Get all registrations tied to a physical device using its device hash. - Lock all registrations tied to a physical device using its device hash. ### Device hash response object Both device hash management endpoints return a device hash response object. For an overview of all response object fields, see the table below: :::CustomTable{tableName="Device hash response object fields" columnWidths="30% 20% 50%"} | **Field** | **Type** | **Description** | | :-- | :-- | :-- | | `devices` | Array | List of device registrations associated with the device hash. | | `devices[].device_id` | UUID | The UUID of the device registration. | | `devices[].lock_status` | String | The lock status of the device registration. See [Lock statuses](#lock-statuses) for possible values. | | `devices[].device_status` | String | The current status of the device registration. See [Device statuses](#device-statuses) for possible values. | ::: ```json title="Example: Device hash response object" { "devices": [ { "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "lock_status": "OPEN", "device_status": "ACTIVATED" } ] } ``` #### Lock statuses For an overview of all lock statuses, see the table below: :::CustomTable{tableName="Lock statuses" columnWidths="40% 60%"} | **Value** | **Description** | | :-- | :-- | | `OPEN` | The device registration is not locked. | | `LOCKED_BY_ADMIN` | The device registration has been locked by an administrator. | | `DEVICE_VERIFICATION_FAILED` | The device registration has been locked due to a failed device verification. | ::: #### Device statuses For an overview of all device statuses, see the table below: :::CustomTable{tableName="Device statuses" columnWidths="40% 60%"} | **Value** | **Description** | | :-- | :-- | | `ACTIVATED` | The device registration is active. | | `DEACTIVATED` | The device registration has been deactivated. | ::: ### Get registrations by device hash You can use the **Get registrations by device hash** endpoint to retrieve all registrations associated with a physical device, identified by its device hash. :::note Note - This operation retrieves both active and deactivated registrations within your organisation. - The `deviceHash` path parameter must be URL-safe Base64 encoded. - The `applicationId` query parameter is optional. ::: ```http title="Get registrations by device hash" GET /api/smart-device/v1/devices/deviceHashes/{deviceHash}?applicationId={applicationId} ``` #### Example ```http title="Example: Request" GET /api/smart-device/v1/devices/deviceHashes/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp ``` ```json title="Example: Response" { "devices": [ { "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "lock_status": "OPEN", "device_status": "ACTIVATED" }, { "device_id": "1cb72f91-3344-4812-a1de-7d845e22bcf1", "lock_status": "OPEN", "device_status": "DEACTIVATED" } ] } ``` ### Lock registrations by device hash You can use the **Lock registrations by device hash** endpoint to lock all active and unlocked registrations associated with a physical device, identified by its device hash. :::note Note - This operation does not include registrations that have already been locked or deactivated. - The `deviceHash` path parameter must be URL-safe Base64 encoded. - The `applicationId` query parameter is optional. ::: :::tip Tip If event callbacks are configured for `DEVICE_LOCKED`, then this operation sends one event callback for each locked registration by default. To suppress these event callbacks for this operation, you can add `suppressEventCallback=true` to the request. ::: ```http title="Lock registrations by device hash" POST /api/smart-device/v1/devices/deviceHashes/{deviceHash}/lock?applicationId={applicationId} ``` :::CustomTable{tableName="Optional query parameters" columnWidths="30% 20% 50%"} | **Parameter** | **Type** | **Description** | | :-- | :-- | :-- | | `applicationId` | String | Scope the lock operation to a specific application. If omitted, the operation applies across all applications in your organisation. | | `suppressEventCallback` | Boolean | Set to `true` to suppress `DEVICE_LOCKED` event callbacks for this lock operation. Default is `false`. | ::: #### Example ```http title="Example: Request" POST /api/smart-device/v1/devices/deviceHashes/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=/lock?applicationId=myApp ``` ```json title="Example: Response" { "devices": [ { "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "lock_status": "LOCKED_BY_ADMIN", "device_status": "ACTIVATED" } ] } ``` --- ## Extension support (iOS) ## About extension support Our iOS extensions feature allows you to extend functionality for your customers beyond your app. This makes it possible for your end-users to authenticate outside of the hosting app, and make content available to them whilst interacting with other apps or parts of the system. Several types of extensions are available, each of which are tied to a single, well-scoped area of the system. You can explore the list of Apple-supported extensions in the [Apple developer documentation](https://developer.apple.com/app-extensions/). ## Example use case With the App Extensions feature, you can make it easier for your customers to add payment cards to their Apple Wallet. - They can add a bank card directly from their Apple Wallet, and authenticate with Encap through the extension, without having to switch apps to their bank or card issuer. - You can implement any of the existing in-app authentication methods such as a PIN or biometrics for this out-of-app authentication. ## Limitations - The following Encap features are no supported in extensions: - App attestation. - Account recovery. - If you have multiple apps using the same shared group, then the secrets and files in that group are not deleted when the app is deleted. To delete them, you must delete all of the apps that use that group. :::tip Note If the app is ever reinstalled, Encap will ignore this data from the group and create new secrets. ::: ### Integration To use this feature, you must: - Enable extension support (`extensionSupport`) in the Encap configuration (`EncapConfig`). - Set up App Groups and Keychain sharing in your app. :::info Want to learn more? For more details, see the [Extension support](/docs/mobile-identity/encap/sdk-ios/configure-features/extension-support.mdx) page in our iOS SDK documentation. ::: ### How it works There is no direct communication between the app extension and the hosting app, therefore the registration data must be stored with Keychain Sharing enabled, and using App Groups to share files. :::tip Note Keychain Sharing and App Groups are only accessible by apps made by members of the same Apple development team. ::: You can read more about how App Extensions work in the [Apple developer documentation](https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionOverview.html). #### New registrations For new registrations, data is stored directly in the Shared Group and Shared Keychain when `extensionSupport` is enabled. No authentication is required before using this feature. #### Existing registrations For existing registrations, registration data must be migrated in order for the feature to work. An authentication is required to do this. For registrations that have biometrics activated, the migration will only take place if a biometric authentication method is used. After the migration, the host app and the app extension will have access to the same data. Diagram showing shared data for existing registrations after migration --- ## Face authentication ## About face authentication Our face authentication feature is an authentication method that uses server-side biometrics. Server-side biometrics are authentication methods that are independent of the device. This means that they can offer cross-device compatibility and centralised management. :::info Want to learn more? To learn more about using face authentication across multiple devices, see our [Device groups](/docs/mobile-identity/encap/features/device-groups.mdx) feature documentation. ::: The face authentication method performs a two-second facial scan with **3D Liveness Check** and **3D Face Matching** on each authentication. This is done within a mobile app and verified on the server, preventing unauthorised access to an account. ### What is a 3D Liveness Check? A **Liveness Check** (also referred to as liveness detection) means that we will verify that it is a physical human in front of the device. We ensure that it is not a photo, deepfake video, or similar spoofing tool. :::info Want to learn more? To learn more about biometric liveness detection, see the [liveness.com](https://www.liveness.com/) web page. ::: ### What is 3D Face Matching? A 3D Face Matching means that we will verify that the human performing the authentication is the same as the one who activated face authentication initially. To do this: 1. At the time of authentication, a **3D FaceMap** is collected together with the liveness data. 2. We match this 3D FaceMap to the 3D FaceMap that we collected during the activation of this authentication method. ### Example use cases Server-side biometrics have the potential to support multiple new use cases, such as: - You want a fast and secure way to perform biometric authentication across devices, in scenarios where native biometrics are not enough. - You want your end-users to share their face enrolment across multiple devices using [Device groups](/docs/mobile-identity/encap/features/device-groups.mdx). - You want a solution if your end-users have invalidated their native biometrics. - You want your end-users to be able to securely reset their authentication credentials. - You want to recover your end-user's account using [Account recovery](/docs/mobile-identity/encap/features/account-recovery.mdx) if: - Their device has been lost, broken or stolen. - They have deleted your application. #### Coming in a future release - You want to prevent phishing attacks when your end-users onboard. - If multiple end-users want to use biometrics on the same device. ### What is the difference between Face ID and face authentication? #### Native biometrics Native biometrics are authentication methods provided by the device's operating system, executed and validated directly on the device for quick and secure authentication using the device's hardware and software. Some examples of native biometrics are Apple Face ID, Apple Touch ID and Android BiometricPrompt. :::tip Our recommendation Native biometrics are fast, secure, and offer a great user experience. We recommend using native biometrics whenever possible. ::: #### Server-side biometrics Server-side biometrics are authentication methods that are independent of the device. These methods offer cross-device compatibility and centralised management, which means that they can be leveraged in some [use cases](#example-use-cases) where native biometrics will not work. An example of server-side biometrics is our face authentication feature. ## How does face authentication work? As with all other authentication methods, face authentication needs to be activated before end-users can start using it. Once you have activated face authentication for your end-users, you can use it to: - Authenticate [(see section on this page)](#how-to-authenticate-with-face-authentication) - Reset authentication credentials - Perform account recoveries [(see section on this page)](#how-to-recover-with-face-authentication) - Prevent fraud during onboarding (possible in a future release) :::note Quotas Activation and authentication operations using face authentication are subject to quota limits. For default quotas and more information, see the [Quotas](#quotas) section. ::: ### Basic flow for a face authentication 1. A FaceMap is captured on the end-user's device. 2. The captured FaceMap is securely transmitted to our server. 3. The server processes and validates the FaceMap, performing the necessary authentication checks. ### How to activate a device for face authentication To activate face authentication, you first need to register a device for your end-user. Once the user has an active device, you can then add face authentication using our `addOrUpdate` method in the SDK. You can learn how to do this in the **Add or update** sections of our SDK documentation: * [**Add or update for Android**](/docs/mobile-identity/encap/sdk-android/authentication-methods/#add-or-update): Learn how to activate a device for face authentication with the Android SDK * [**Add or update for iOS**](/docs/mobile-identity/encap/sdk-ios/core-operations/#add-or-update): Learn how to activate a device for face authentication with the iOS SDK #### Device groups Our [Device groups](/docs/mobile-identity/encap/features/device-groups.mdx) feature is a key enhancement for face authentication. When an end-user enrols their face for the first time, a device group is implicitly created. This allows other devices in the same group (running SDK 3.22 or later) to dynamically activate face authentication without interaction, providing a seamless, cross-device experience where one activated face authentication works everywhere. If the end-user already has an active face enrolment on another device within a [Device group](/docs/mobile-identity/encap/features/device-groups.mdx), then new, compatible devices will have face authentication dynamically activated. This means that they can start authenticating immediately without a new enrolment. #### What does an activation look like? The following diagram illustrates what it could look like to activate face authentication, from the perspective of your end-users. Diagram showing end-user flow for activating face authentication #### Diagram for activation The following sequence diagram illustrates an activation of face authentication. Sequence diagram showing activation of face authentication ### How to authenticate with face authentication You can initiate a face authentication by setting `DEVICE_SERVER_SIDE_FACE` as the `authMethod` when you start the authentication operation. See [Authentication methods](https://demo.encapsecurity.com/pt/api/docs/index.html#authMethods) in the Encap API reference documentation for details. #### What does an authentication look like? The following diagram illustrates what it could look like to authenticate with face authentication, from the perspective of your end-users. Diagram showing end-user flow for authentication with face authentication #### Diagram for authentication The following sequence diagram illustrates an authentication with face authentication. Sequence diagram showing authentication with face authentication ### How to recover with face authentication Our account recovery feature supports server-side face authentication as an authentication method. We recommend this for recovery, as: - It is more user-friendly, with no recovery code to remember. - It enhances security by not having a recovery code which could be shared. To learn about this feature and how to implement it, see our [Account recovery](/docs/mobile-identity/encap/features/account-recovery.mdx) feature documentation. ## API integration The following service provider REST APIs have been extended with the `DEVICE_SERVER_SIDE_FACE` authentication method. ### Activation The `activated_authentication_methods` field can contain `DEVICE_SERVER_SIDE_FACE` for enrolment operations. :::tip Note For further details, see [The enrolment object](https://demo.encapsecurity.com/pt/api/docs/index.html#enrollObject) in our Encap API reference documentation. ::: ### Authentication The `authentication_method` parameter can contain `DEVICE_SERVER_SIDE_FACE` for authentication operations. :::tip Note For further details, see [Authentication](https://demo.encapsecurity.com/pt/api/docs/index.html#_authentication) in our Encap API reference documentation. ::: ### Device object The `activated_authentication_methods` field in the device object can now contain `DEVICE_SERVER_SIDE_FACE`. :::tip Note For further details, see [The device object](https://demo.encapsecurity.com/pt/api/docs/index.html#deviceObject) in our Encap API reference documentation. ::: ## How to configure face authentication To use our face authentication feature, you need to: - Contact Signicat to get access to this feature. - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK Learn how to configure the mobile SDK for face authentication. * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/face-authentication): Learn how to configure the Android SDK for face authentication * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/face-authentication): Learn how to configure the iOS SDK for face authentication ### Configure the application configuration To enable the server-side authentication method, you need to update your application configuration with the following parameters: :::CustomTable | **Configuration key** | **Value** | **Allowed values** | **Default** | | :-- | :-- | :-- | :-- | | `SERVER_SIDE_FACE_CREDENTIALS` | The client credentials used for requesting authentication tokens from our authentication server. The value will be `base64(CLIENT_ID:CLIENT_SECRET)` obtained when creating an API client in the Signicat Dashboard. | Base64 | | | `ALLOWED_AUTH_METHODS` | New allowed value added to the comma-separated list: `DEVICE:SERVER_SIDE_FACE` | `DEVICE:SERVER_SIDE_FACE` in addition to existing allowed values. | `DEVICE`, `DEVICE:PIN` | | `ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE` | New allowed value added to the comma-separated list: `DEVICE:SERVER_SIDE_FACE` | `DEVICE:SERVER_SIDE_FACE` in addition to existing allowed values. | `DEVICE:PIN` | ::: ## Quotas All performed activation and authentication operations which use face authentication are subject to the default quota limits. If your app exceeds the default quotas outlined in the tables below, then your requests may fail. To update the quota limits, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### Production environment Default quotas in the production environment: | **Quota name** | **Default limit** | | :-- | :-- | | `Face authentications per account per day` | `1000` | | `Face authentications per account per minute` | `10` | | `Face registrations per account per day` | `1000` | | `Face registrations per account per minute` | `10` | ### Sandbox environment Default quotas in the sandbox environment: | **Quota name** | **Default limit** | | :-- | :-- | | `Face authentications per account per day` | `100` | | `Face authentications per account per minute` | `10` | | `Face registrations per account per day` | `100` | | `Face registrations per account per minute` | `10` | --- ## Geofencing ## About geofencing Our geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. By limiting the use of Encap SCA activations (registrations/enrolments) and authentications to certain regions​, you can reduce the chance of fraud. ### Example use case You want to be notified of transactions that occur in a specific country. This means that if someone tries to activate (register/enrol) or authenticate in this country, then you can either block the transaction or be notified that it is happening. ## How does geofencing work? When geofencing is enabled, the client will send the country code of the location of the device to the server. The server will verify the location and limit the use of the device based on the configuration in your application configuration and what you have set as your allowed regions. ### What are allowed regions? Geofencing allowed regions are defined as: > **allowed continents** + **allowed countries** - **denied countries** ### How are countries and continents defined? Countries are identified in an ISO 3166-1 alpha-2 two-letter country code format. Geofencing regions can also be defined on continent level. In this instance, the Encap server maps between the client country and its associated continent. The Encap server contains a default mapping which is defined according to ISO 3166 and the data from [GeoNames.org](https://download.geonames.org/export/dump/countryInfo.txt). ### Basic flow for geofencing 1. The server informs the client about the current geofencing mode. 2. Depending on the geofencing mode, the client determines whether to call the external geocoder platform service with location as a parameter. 3. If the external geocoder platform service was called, then it will return the address from the location. 4. The client sends the country from the address to the server. :::tip Note The region must be allowed in the application configuration and the end-user must grant location permissions to the app. ::: 5. When the transaction completes, the server will evaluate if the country reported by the client is within the allowed regions, according to the following rule: ```java if (country in && clientCountry not in || country in ) { // Success } else { // Failure - deny reject transaction (if REQUIRED mode) } ``` 6. If the transaction was performed by a mobile client outside of the allowed geofencing boundaries, then the result depends on which mode you have configured geofencing to use: - If geofencing is set to the `REQUIRED` mode, then the transaction will fail. - If geofencing is set to the `OPTIONAL` mode, then the transaction will succeed, but the result of the evaluation is reported to you together with the actual country. It is up to you what action to take on the result. ### Risks - For iOS, with a compromised system such as a jailbroken device, it is possible to fake the location that is coming from the location API. - For Android, it is possible to install a location provider that can fake your location. This can be done without rooting the device. To help mitigate these risks, you can shield the app or implement app attestation. ## API integration #### Geofencing result object The geofencing result is provided in the REST response as the `geofencing` object. To learn more about this, you can refer to the [Encap API reference documentation](https://demo.encapsecurity.com/pt/api/docs/index.html#geofencing-object). The geofencing object is: - A session object for [activation](https://demo.encapsecurity.com/pt/api/docs/index.html#enrollObject) (registration/enrolment). - A session object for [authentication](https://demo.encapsecurity.com/pt/api/docs/index.html#authObject). ### Response fields :::CustomTable | **Field** | **Type** | **Description** | | :-- | :-- | :-- | | `country_code` | String | The country code in an ISO 3166-1 Alpha-2 format, as reported by the client. | | `client_status` | String | The status of the geofencing operation, as reported by the client. See [Geofencing client statuses](#geofencing-client-statuses) for possible values. | | `server_boundary_validation` | String | The status of the geofencing server validation, after evaluating the country against the allowed region. This can be either `SUCCESS` or `FAILURE`. | ::: **Example: Geofencing result** ```json "geofencing" : { "country_code" : "NO", "client_status" : "OK", "server_boundary_validation" : "SUCCESS" } ``` #### Geofencing client statuses If a country code is obtained successfully, then the geofencing client status (`client_status`) will be populated with `OK`. If the device fails to obtain a location, or if the client's reverse geocode request fails, then the `client_status` field will be populated with an appropriate status from the table below. :::CustomTable | **Client status** | **Description** | | :-- | :-- | | `OK` | The country code was obtained. | | `LOCATION_NOT_ENABLED` | Either: The location was not requested by the app. The end-user declined access to location services for the app on their device. | | `LOCATION_TIMEOUT` | The device did not obtain a location within the configured accuracy before timeout. | | `LOCATION_MOCKED` | **Android devices only** The location of the device was mocked.This is based on the location methods [isFromMockProvider()](https://developer.android.com/reference/android/location/Location#isFromMockProvider()) and [isMock()](https://developer.android.com/reference/android/location/Location#isMock()), which indicate whether this location is marked as a mock location. **Note**: To test faking the GPS location of the device, you can download and install a mock location app, then enable it in the [Developer options](https://developer.android.com/studio/debug/dev-options) on the device. | | `GEOCODER_NOT_SUPPORTED` | **Android devices only** Geocoder is not supported on the device. | | `GEOCODER_NETWORK_ERROR` | Either: The geocoder network or service is not available. Too many requests have been made to the geocoder service (offered by Apple or Google), as it is rate-limited for each app. | | `GEOCODER_UNEXPECTED_ERROR` | An unexpected geocoder error occurred. | | `GEOCODER_TIMEOUT` | The geocoder call did not finish within the time limit. | | `GEOCODER_NO_RESULT_FOUND` | The reverse geocode request yielded an empty result for the current location. | ::: ### Override configuration for a specific device For authentication operations, you can modify the geofencing configuration for a specific device using our REST APIs. This will override the geofencing configuration in the application configuration. #### Geofencing configuration object :::CustomTable{columnWidths="20% 20% 50%"} | **Field** | **Type** | **Description** | | :-- | :-- | :-- | | `mode` | String | The geofencing mode. | | `allowed_continents` | String | Comma-separated list of continents where authentication **is allowed** for a specific device, in a two-letter continent code format. | | `allowed_countries` | String | Comma-separated list of countries where authentication **is allowed** for a specific device, in an ISO 3166-1 alpha-2 two-letter country code format. These countries are in addition to those covered by the allowed continents parameter. | | `denied_countries` | String | Comma-separated list of countries where authentication **is not allowed** for a specific device, in an ISO 3166-1 alpha-2 two-letter country code format. These countries will be excluded from those covered by the allowed continents parameter. | ::: **Example: Geofencing config object** ```json { "mode" : "OPTIONAL", "allowed_continents" : "EU", "allowed_countries" : "US", "denied_countries" : "XX" } ``` #### Get geofencing configuration for a device You can use this endpoint to retrieve the geofencing configuration for a device. As a result, the geofencing config object is returned. ``` GET /api/smart-device/v1/devices/{deviceId}/geofencing ``` #### Update geofencing configuration for a device You can use this endpoint to update the geofencing configuration for a device. As a result, the geofencing config object is returned. ``` PUT /api/smart-device/v1/devices/{deviceId}/geofencing ``` #### Delete geofencing configuration for a device You can use this endpoint to delete the geofencing configuration for a device. ``` DELETE /api/smart-device/v1/devices/{deviceId}/geofencing ``` ## How to configure geofencing To use our geofencing feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK Learn how to configure the mobile SDK for geofencing. * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/geofencing): Learn how to configure the Android SDK for geofencing * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/geofencing): Learn how to configure the iOS SDK for geofencing ### Configure the application configuration Learn how to configure the application configuration for geofencing. #### Geofencing modes The geofencing feature can be used in multiple modes: :::note OFF The `OFF` mode means that a device location check is not performed. By default, geofencing is always turned `OFF`. ::: :::note OPTIONAL The `OPTIONAL` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will still be performed. It is up to you what action is taken on the result. ::: :::note REQUIRED The `REQUIRED` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will fail. ::: #### Setting the properties The configuration is split into a set of properties for activation (registration/enrolment) and authentication, so that you can enforce different rules for the different operations. To enable geofencing, you need to set the following properties in the application configuration: :::CustomTable{minTableSize="1000px" columnWidths="25% 25% 25% 25%"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `GEOFENCING_ACTIVATION_MODE` | Determines if or how geofencing is used for activation (registration/enrolment). | `OFF`, `OPTIONAL`, `REQUIRED` | `OFF` | | `GEOFENCING_ACTIVATION_ALLOWED_CONTINENTS` | Comma-separated list of continents where activation (registration/enrolment) **is allowed**, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `GEOFENCING_ACTIVATION_ALLOWED_COUNTRIES` | Comma-separated list of countries where activation (registration/enrolment) **is allowed**, in an ISO 3166-1 alpha-2 two-letter country code format These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_ACTIVATION_DENIED_COUNTRIES` | Comma-separated list of countries where activation (registration/enrolment) **is not allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_AUTHENTICATION_MODE` | Determines if or how geofencing is used for authentication. | `OFF`, `OPTIONAL`, `REQUIRED` | `OFF` | | `GEOFENCING_AUTHENTICATION_ALLOWED_CONTINENTS` | Comma-separated list of continents where authentication **is allowed**, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `GEOFENCING_AUTHENTICATION_ALLOWED_COUNTRIES` | Comma-separated list of countries where authentication **is allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_AUTHENTICATION_DENIED_COUNTRIES` | Comma-separated list of countries where authentication **is not allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_TIMEOUT` | The maximum time (given in milliseconds) to wait for the location lookup and reverse geocoding to complete on the client. The timing starts when the client calls the finish operation. If the timeout is exceeded, then the client will continue without a country. | From `0` to `MAXINT`. | `10000` | ::: ##### New countries In the rare instance where a new country is defined, the country-continent mapping can be overridden in the property file `/core/config/encap-cluster-geofencing.properties`. For example, if a new country in Europe was defined in ISO 3166 with country code `XX`, then you can configure this in the property file using: ``` # Mapping of ISO-3166 alpha2 country code to continent code geofencing.continentForCountry.XX=EU ``` :::warning Important You must keep this configuration synchronised across all servers in the cluster. ::: --- ## Hardware-protected keys In addition to dynamically generated software keys, we use hardware-protected keys to strengthen proof-of-possession and maximise device security. The probability that an attacker is able to obtain the private keys that are stored in the secure hardware on a device and then use them outside the device without breaking it on a hardware level is very low. ## How do hardware-protected keys work? A hardware-protected key pair is generated in hardware, typically on a trusted execution environment (TEE) or trusted platform module (TPM). The private key will never leave the hardware. As a result, all operations that require the private key are performed in the secure hardware on the device. For example, operations like `encrypt`, `decrypt`, `sign` and `verify` that use the private key are performed in the secure hardware. Even a rooted device still protects the hardware keys from extraction, and cloning of a key can not be performed on a rooted device. It is therefore very unlikely that an attacker is able to steal a key stored in the secure hardware and use it outside of the device. ### Activation Sequence diagram showing hardware-protected keys activation A typical flow for activation of a hardware-protected key is as follows: 1. The Encap SDK generates a key pair in the secure hardware. 2. The secure hardware returns the public hardware (HW) key to the Encap SDK. 3. The Encap SDK returns this key to the Encap server over the secure channel in the `finish activation` request. 4. The Encap server stores the public HW key on the registration, and this key will be used to verify all future authentications. ### Authentication Sequence diagram showing hardware-protected keys authentication For a device that is activated with HW keys, an additional security check will be executed for each authentication. The flow is as follows: 1. The Encap SDK signs the authentication challenge received from the Encap server in the `start authentication` request, with the hardware-protected private key. 2. The signed challenge is passed back to the Encap server in the `finish authentication` request over the secure channel. 3. The signed challenge is verified on the server side with the HW public key. ## How to implement hardware-protected keys :::note Note This feature does not require any client configuration to enable it. ::: ### Prerequisites All devices that have support for hardware keys use this security feature by default. These are: - Most devices using Android 6 devices. - All devices using Android 7 or later. - All devices using iOS 10 or later / devices with Secure Enclave. :::warning Important Devices that do not support hardware-protected keys will only use software keys. ::: ### 1. Choose a validation strategy We offer three validation strategies, each of which involves validating the hardware signature on the Encap server. You need to choose which validation strategy you want to set. :::note Note Only Encap server versions 3.22 and above support the `REQUIRED` strategy. ::: :::CustomTable | **Validation strategy** | **Description** | | :-- | :-- | | `REQUIRED` | The hardware key validation is mandatory for all devices. Activation operations fail if the client reports that it cannot generate a hardware-supported key or any technical failure occurred during key generation. Authentication operations fail if the client does not provide a valid signature from its hardware-supported key. | | `REQUIRED_IF_SUPPORTED` | The hardware key validation is only mandatory if the device supports hardware keys. Activation and authentication operations are rejected if the provided signature is invalid. **Note**: This is the default validation strategy. | | `OPTIONAL` | The hardware key validation is performed without enforcement. Activation and authentication operations do not fail if the hardware signature is invalid, but generate risk attributes such as: `hw_key_client_status` `hw_key_server_result` | ::: ### 2. Configure the application configuration To set your chosen validation strategy, you need to configure the application configuration on the Encap server using the following parameter: :::CustomTable | **Parameter name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `HWKEY_VALIDATION_STRATEGY` | Defines the validation policy for hardware-protected keys. | `REQUIRED` `REQUIRED_IF_SUPPORTED` `OPTIONAL` | `REQUIRED_IF_SUPPORTED` | ::: ### 3. Enable risk data When risk data is enabled, the result of the hardware signature validation is returned as part of the risk data set. To enable this, you need to configure the application on the Encap server using the following parameter: :::CustomTable | **Parameter name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `ENABLED_RISK_DATA` | Defines which risk data to store. **Note**: Must be given as a comma-separated list. | To enable hardware validation risk attributes, you need to either Set `ALL` (this includes all available risk data). Set `HwKeyClientStatus` and `HwKeyServerResult` (in addition to any other risk data that you want to return). | The default value is empty. This means that no risk data is enabled. | ::: ### 4. Validation result When the risk attributes are enabled, the result of the hardware-protected key validation is returned to you in the following risk attributes: :::CustomTable | **Risk attribute** | **Type** | **Description** | | :-- | :-- | :-- | | `hw_key_client_status` | String | What status the client device reported the hardware-protected key to be for the operation. | | `hw_key_server_result` | String | The result of the hardware-protected key signature processing in Encap. | ::: :::tip Note For possible values, see the tables under **Hardware protected key client statuses** and **Hardware protected key server result** in our [API reference documentation](https://demo.encapsecurity.com/pt/api/docs/index.html#risk-attributes-object). ::: --- ## Features You can learn about Encap's features in our feature guides. * [**Account recovery**](/docs/mobile-identity/encap/features/account-recovery): Allow your end-users to recover their registration without the need for reactivation * [**App attestation**](/docs/mobile-identity/encap/features/app-attestation): Strengthen your application's security by preventing third-party use of our APIs * [**Device groups**](/docs/mobile-identity/encap/features/device-groups): Create groups of devices which can share face authentication across devices * [**Device hash blocking**](/docs/mobile-identity/encap/features/device-hash-blocking): Block a device from registering or recovering on the Encap server * [**Device hash locking**](/docs/mobile-identity/encap/features/device-hash-locking): Get and lock all registrations tied to a device hash using a single operation * [**Extension support (iOS)**](/docs/mobile-identity/encap/features/extension-support): Authenticate your end-users outside of your application * [**Face authentication**](/docs/mobile-identity/encap/features/face-authentication): Authenticate your end-users with face authentication across devices * [**Geofencing**](/docs/mobile-identity/encap/features/geofencing): Reduce fraud by limiting the use of your app to certain regions * [**Hardware-protected keys**](/docs/mobile-identity/encap/features/hardware-protected-keys): Strengthen proof-of-possession and maximise device security * [**Mobile client data**](/docs/mobile-identity/encap/features/mobile-client-data): Securely attach custom data to authentication and add or update flows * [**Mobile client diagnostics**](/docs/mobile-identity/encap/features/mobile-client-diagnostics): Pass debug data and error reports from the client to the server for debugging purposes * [**Multi-registration**](/docs/mobile-identity/encap/features/multi-registration): Activate multiple registrations within one mobile application * [**Push notifications**](/docs/mobile-identity/encap/features/push-notifications/): Inform the end-user that something is happening in your app that requires their attention * [**Reactivation**](/docs/mobile-identity/encap/features/reactivation): Allow your end-users to reactivate and create new credentials on the same registration ID :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Mobile client data ## About mobile client data Our mobile client data feature enables you to attach custom data when starting an authentication or updating an authentication method. This data is held securely during the flow, then is returned to your service when the operation is complete. This allows you to maintain state or pass essential metadata throughout the flow, ensuring that the context of the original request is preserved. ## Example use cases ### Use case 1: Maintain transaction context You can use mobile client data to maintain the context of the transaction. For example: 1. Your end-user initiates a payment in your banking app. 2. Your app passes the transaction details as mobile client data, such as the amount, recipient and unique transaction ID. 3. When your end-user authenticates to approve the payment, this data is returned to the Encap server. 4. The service verifies that the details of the approved transaction match the initial request, preventing data loss or tampering during the flow. ### Use case 2: Pass client metadata You can use mobile client data to pass metadata about the client, then utilise this data as required. For example: 1. You send information about the client environment, such as the application name and version, or a custom user agent string. 2. You use this metadata for server-side logging, analytics, or enabling specific logic or feature flags based on the client that initiated the request. ## How to implement mobile client data When initiating an authentication or adding an authentication method, you provide an optional string of mobile client data. This string must adhere to the following rules: - **Maximum size**: The string must not exceed 1024 bytes and has to be UTF-8 encoded. - **Character encoding**: The string must not contain 4-byte UTF-8 characters. This includes most emojis and certain other symbols, for example: :tada: and :+1:. To learn about how this might look for both platforms, see the [Android](#android-examples) and [iOS](#ios-examples) examples below. ### Android examples The example below shows an Android authentication flow with mobile client data: ```kotlin title="Example: Start authentication flow with mobile client data" // Controller interface fun startAuthentication(clientData: String?, appCallback: AsyncCallback) // Usage controller.startAuthentication("clientDataExample", appCallback) ``` The example below shows an Android add or update flow with mobile client data: ```kotlin title="Example: Start add or update flow with mobile client data" // Controller interface fun startAddOrUpdate(startParameter: StartAddOrUpdateParameter, appCallback: AsyncCallback) // Usage val startParameter = StartAddOrUpdateParameter("clientDataExample", null) controller.startAddOrUpdate(startParameter, appCallback) ``` ### iOS examples The example below shows an iOS authentication flow with mobile client data: ```swift title="Example: Start authentication flow with mobile client data" // Controller interface public func startAuthentication(clientOnly: Bool, clientData: String? = nil, onCompletion: @escaping (Result) -> ()) // Usage let clientData = "clientDataExample" EncapController.shared.startAuthentication(clientOnly: false, clientData: clientData) { result in switch result { case .success(let successResult): //Success case .failure(let errorResult): // Error } } ``` The example below shows an iOS add or update flow with mobile client data: ```swift title="Example: Start add or update flow with mobile client data" // Controller interface public func startAddOrUpdate(startAddOrUpdateParameter: StartAddOrUpdateParameter? = nil, onCompletion: @escaping (Result) -> ()) // Usage let clientData = "clientDataExample" let startParam = EncapStartAddOrUpdateParameter(clientData: clientData, selectedAuthMethod: .device) EncapController.shared.startAddOrUpdate(startAddOrUpdateParameter: startParam, onCompletion: { onCompletion in switch onCompletion { case .success(let successResult): // Success case .failure(let errorResult): // Error } }) ``` --- ## Mobile client diagnostics Our mobile client diagnostics feature provides you with two different methods to gather diagnostic information from the devices of your end-users. The table below provides you with a high-level overview of what the methods are and how to use them: :::CustomTable{tableName="Client debug data and client error reporting" columnWidths="30% 35% 35%"} | **Aspect** | **Client debug data** | **Client error reporting** | | :-- | :-- | :-- | | **Primary use case** | Troubleshoots specific support cases in depth. | Monitors continuously for unexpected client errors. | | **Data granularity** | Gathers detailed device and sensor information for each operation. | Reports on unexpected client-side errors only. | | **Default status** | Disabled | Enabled | | **Intended duration** | Temporary | Continuous | ::: ## Client debug data Our client debug data feature enables the Encap server to receive debug information from elements and sensors available on the mobile device, such as disk space and available memory. It is designed to be enabled during error or support situations where additional data can help in finding the error; it is not intended to be enabled continuously. ### About client debug data - It is configured in the application configuration and is disabled by default. - The data is logged to a separate file on the Encap server. - It is possible to enable the feature for Android and iOS devices independently, or for both platforms simultaneously. ### Example data Examples of data that can be logged using this feature include: - The amount of disk space available. - The amount of memory left on the mobile device, given in megabytes (MB). - The process ID of the app performing the operation. - The thread ID performing the operation. - Whether or not the mobile device is currently in battery-saver/low-power mode. - Whether the operation is performed over a Wi-Fi or cellular connection. - The timestamp of the request as reported from the mobile device. ### How to implement it #### 1. Configure the application configuration To enable client debug data, you need to enable it in your application configuration with the following parameter on the Encap server. :::CustomTable | **Configuration key** | **Allowed value** | **Default value** | | :-- | :-- | :-- | | `CLIENT_DEBUG_DATA_ENABLED_OS_TYPES` | It can be empty, `ANDROID`, `IOS`, or a comma-separated list such as `ANDROID,IOS`. | | ::: #### 2. Configure the logback file To write the data to the logs, you need to ensure that the `logback.xml` file is configured correctly. - If you are using a new installation of the Encap server, then the default configuration writes all client debug data to `logs/clientDebugData.log`. - If you are upgrading and already have a custom `logback.xml` file, then you can enable client debug data by updating it with the configuration below: ```xml title="Example: Configure logback file for client debug data" ./logs/clientDebugData.log ./logs/clientDebugData.%i.log.gz 1 10 10MB %d %X{requestCorrelationId} %m%n ``` #### 3. Configure the mobile SDK The mobile SDK will never send any debug data without it being configured on the Encap server. In addition, each registration on a device can opt out from sending debug data. To do this, the app needs to set the `allowDebugData` parameter to `false` in its configuration: :::CustomTable | **EncapConfig** | **Allowed values** | **Default value** | | :-- | :-- | :-- | | `allowDebugData` | It can be either `true` or `false`. **Note**: If you set this to `false`, then the controller will not send debug data, even if the Encap server is configured to do so. | `true` | ::: ### Technical details #### Log output The log output for client debug data is configured in the `logback.xml` file. This gives an opportunity to add the logs to any appender and adjust the output format to fit into any external log analysis tool. By default, the data is stored in the `clientDebugData.log` file in the same folder as the other logs. The appender is set up to roll over after 10 MB and stores the previous log file as a compressed `gz` file. :::note Note The 10 last files are stored. ::: #### Log size Client debug data is logged for each operation: - Activation - Authentication - Recovery Depending on the number of mobile devices, this can potentially produce many entries. To limit or extend the amount of data stored on the server, you can update the configuration in the `logback.xml` file. #### Log format Client debug data is stored in the following format: ```json title="Example: Client debug data format" date correlationId registrationId clientDebugData 2022-05-18 13:06:31,410 561570bb-d6ab-11ec-8a74-0a2622afb44b 0028211c-6512-4f44-8fd6-6fbb1d0a55d7 {"processId":"24057","threadId":"123","connectionType":"WiFi","applicationState":"active","clientRequestTime":"15:05:20 + 2060","isProtectedDataAvailable":"true","lowPowerMode":"false","isIosAppOnMac":"false","freeDiskSpace":"21,454"} 2022-05-18 13:06:31,622 5637ecdc-d6ab-11ec-8a74-0a2622afb44b 0028211c-6512-4f44-8fd6-6fbb1d0a55d7 {"isIosAppOnMac":"false","connectionType":"WiFi","processId":"24057","threadId":"123","freeDiskSpace":"21,454","applicationState":"active","lowPowerMode":"false","isProtectedDataAvailable":"true","clientRequestTime":"15:05:42 + 4290"} ``` :::note Note The `correlationId` is used to correlate all log entries during a request. ::: #### Logged data If client debug data is enabled, then all available debug information is sent to the Encap server. The list of available attributes varies depending on the mobile platform. You can see which attributes are returned in the **Collected data** appendix in our SDK documentation: * [**Android client debug data**](/docs/mobile-identity/encap/sdk-android/publish-your-app/collected-data#client-debug-data): See the list of client debug data attributes for Android * [**iOS client debug data**](/docs/mobile-identity/encap/sdk-ios/publish-your-app/collected-data#client-debug-data): See the list of client debug data attributes for iOS ## Client error reporting For continuous reporting of unexpected errors occurring on the mobile devices, you can use client error reporting. It is designed to be enabled continuously so that you can monitor and gather information about unexpected errors, helping you to find the cause of bugs. ### About client error reporting - It is enabled by default. - The data is logged to a separate file on the Encap server. ### How to implement it To write the error reports data to the logs, you need to update the `logback.xml` file. - If you are using a new installation of the Encap server, then the default configuration writes all client error reporting data to `logs/clientError.log`. - If you are upgrading and already have a custom `logback.xml` file, then you can enable client error reporting data by updating it with the configuration below: ```xml title="Example: Configure logback file for client error reporting data" ./logs/clientError.log ./logs/clientError.%d{yyyy-MM-dd}.log ${CLIENT_ERROR_LOG_RETAIN_DAYS} %d %X{requestCorrelationId} %m%n ``` ### Technical details #### Log output The log output for client error reporting is configured in the `logback.xml` file. This gives an opportunity to add the logs to any appender and adjust the output format to fit into any external log analysis tool. By default, the data is stored in the `clientError.log` file in the same folder as the other logs. The appender is set up to roll over daily and stores the logs for the number of days configured in the `CLIENT_ERROR_LOG_RETAIN_DAYS` property. #### Log retention The number of days to retain the logs is configured by the `CLIENT_ERROR_LOG_RETAIN_DAYS` property in the `logback.xml` file. In the example configuration above, this is set to `30` days. --- ## Multi-registration ## About multi-registration Our multi-registration feature allows you to activate and manage multiple independent registrations within a single mobile app. This is useful for apps that need to support multiple end-user accounts or identities concurrently. Diagram showing multi-registration use case ### Example use cases - Multiple end-users share the same mobile device, and each person needs to securely access their own account within the app. For example, this could be the case with family or colleagues sharing the same tablet. - An end-user has multiple accounts with separate authentication credentials for each, which they need to access on the same mobile device. For example, this could be the case if the end-user has a personal account and a business account. ## How does multi-registration work? To use multi-registration, you must create multiple controllers within the SDK, where each controller corresponds to a unique registration. When you create a new controller for a multi-registration app, you need to give the controller a unique name. This name is then later used to identify the controller. ### Handling push notifications When you use our multi-registration feature, you may need to make considerations about how push notifications are handled. A push notification indicates to the end-user that something is happening for one of the registrations in the app that requires attention, however: - There is no information in the push message that indicates for which registration the push was triggered. - The app does not know what controller to start the authentication for. To handle this in your app, there are two alternatives: #### Send information in the push payload When you start an authentication, you have the option to set a `pushPayload` which is passed in the push notification. You can use this to give the app information about what controller to use. :::warning Important The push payload is not a secure channel. This means that you should not use it to share sensitive information such as secrets. ::: #### Verify on all controllers When your end-user opens the app, start with iterating through all of controllers. You can run a `startAuthentication` to check if there is any ongoing activity for that registration. ## How to implement multi-registration To use our multi-registration feature, you only need to create multiple named controllers within the SDK; no additional configuration is required. The process for creating a controller is different for Android and iOS. ### Android To create a new controller with a unique name on Android: ```kotlin title="Example: Create a named controller for Android" Controller controller = AndroidControllerFactory.getInstance(androidContext, "registrationA"); ``` ### iOS To initialise the `EncapController` with a unique name on iOS: ```swift title="Example: Create a named controller for iOS" let controller = EncapController(name: "registrationA") ``` --- ## Create APNs token For iOS, we use Apple Push Notification service (APNs) to send push notifications. To be able to use this, you need to create an APNs token for your application: ## 1. Create an APNs provider authentication token 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **Keys**. Next, click the **+** button to register a new key. 4. Add a **Key Name** and optionally a **Key Usage Description**. 5. Tick the **ENABLE** box for **Apple Push Notifications service (APNs)**, then click the **Configure** button. 6. In the **Environment** dropdown menu, select the desired option, then click the **Save** button. 7. Click the **Continue** button, then click the **Register** button. 8. Copy the displayed Key ID (`KeyID`) and store it in a secure place. 9. Click the **Download** button to download `.p8` file containing the token, then store it in a secure place. ## 2. Find your Team ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Membership details**. 2. Copy the **Team ID** and store it in a secure place. ## 3. Find your Bundle ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the application that you are configuring the APNs token for. 4. Copy the **Bundle ID** and store it in a secure place. ## 4. Add to enabled capabilities You need to add push notifications as enabled capabilities for the provisioning profile when you are publishing your app. To do this: 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the App ID that you want to update, then click **Edit**. 4. Select the checkbox to enable push notifications. :::tip Tip You can also enable any other app capabilities that you want to allow, such as time-sensitive notifications. To learn more about this, see the [Time-sensitive notifications](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications/#time-sensitive-notifications) section in our iOS SDK **Push notifications** documentation. ::: 5. Click the **Save** button. :::note Note If a warning dialogue box appears, then click the **Confirm** button to finalise your changes. ::: --- ## Create Firebase project For Android, we use Firebase Cloud Messaging (FCM) to send push notifications. To be able to use this, you need to create a Firebase project for your application: ## 1. Create a new Firebase project You need to create a Firebase project so that you can download the push configuration file for the Android platform. To do this: 1. Log in to the [Firebase Console](https://console.firebase.google.com/u/0/) with your Google account. If you do not have one, then you can create a Google account for free. 2. On the Firebase Console home page, click the **Add project** button. 3. Enter a project name. This name should be relevant to your name or business. 4. **Optional**: Choose whether to enable Google Analytics for your project. This is not a requirement, but can be enabled at this point if you want analytics tracking. 5. Click the **Create project** button, then click **Continue**. ## 2. Download the push configuration file You must generate the platform-specific configuration file that links your app to Firebase services. This configuration file is necessary to enable push notifications. To do this: 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **General** tab, then scroll down to the **Your Apps** section. 3. Click the **Add app** button, then select the **Android** platform. 4. Enter your Android app's package name. :::tip Tip You can also add a nickname for the app and specify the SHA-1 if required. The SHA-1 is optional for push notifications, but may be required for other Firebase services. ::: 5. Click the **Register app** button. 6. Download the `google-services.json` configuration file and store it in a secure place. 7. Skip the next steps, then click the **Continue to console** button. ## 3. Create the service account key 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **Service accounts** tab and click the Google Cloud link for **All service accounts**. This will open the Google Cloud Project associated with your Firebase project. 3. In the left-side menu click on **Service Accounts** 4. With Firebase Admin SDK selected, press **Generate new private key**. 5. When the new `.json` key file is downloaded, ensure that you store it in a secure place. --- ## Push notifications ## About push notifications Our push notifications feature enables you to inform the end-user that something is happening in your app that requires their attention. This is an optional feature that you can configure in the application configuration. If you enable push, you can also toggle it when initiating the authentication. :::note Note Push notifications can be used to improve the end-user experience, but you are not required to use them. They have no impact on the authentication operation itself. ::: ### Example use cases - You want to notify your end-users who are attempting to log in to your website that they have a login request to approve. - You want to notify your end-user on their mobile device that they have a transaction to authorise. ## How to implement push notifications To implement our push notifications feature, you need to: - [Configure the application configuration](#configure-the-application-configuration). - [Configure the mobile SDK](#configure-the-mobile-sdk). ### Configure the application configuration To use push notifications, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to receive push notifications. #### Prerequisites Before you start, you need to create an APNs token (iOS) and set up a Firebase project (Android). To learn how to do this, use the buttons below: * [**Android prerequisites**](/docs/mobile-identity/encap/features/push-notifications/create-firebase-project): Learn how to create a Firebase project for your app * [**iOS prerequisites**](/docs/mobile-identity/encap/features/push-notifications/create-apns-token): Learn how to create an APNs token for your app #### Configure push notifications Once you have completed the prerequisites, you can configure your app to use push notifications. :::warning Configure Android and iOS simultaneously Currently, you need to configure push notifications for Android and iOS simultaneously. ::: ##### 1. Add APNs token You need to add the APNs token using the values obtained when you created it in the Apple Developer Program Portal. To do this: 1. See [Add APNs provider token](https://demo.encapsecurity.com/pt/api/docs/index.html#_add_apns_provider_token) in the Encap REST API reference documentation. 2. Supply the following values in the request: | **Field name** | **Description** | | :-- | :-- | | Name | Give the APNs token a name. | | Description | Give the APNs token a description. | | Key ID | Add the Key ID that you obtained when you created the token. | | Team ID | Add your Team ID that you obtained from **Membership details**. | | Private key | Add the private key from the `.p8` file that you downloaded when you created the token. **Note**: You can open the `.p8` file using a text editor app. | ##### 2. Enable push notifications You need to enable and configure push notifications in your application configuration. To do this: 1. See [Update application configuration](https://demo.encapsecurity.com/pt/api/docs/index.html#_update_application_configuration) in the Encap REST API reference documentation. 2. At a minimum, supply the following values in the request: | **Property name** | **Required action** | | :-- | :-- | | `NATIVE_PUSH_ENABLED` | Set this to `TRUE`. | | `FIREBASE_SERVICE_ACCOUNT` | Add the contents of the `.json` key file obtained in the prerequisite step. | | `apns_uuid` | Add the ID of the APNs token that you created. | | `APNS_BUNDLE_ID` | Add the bundle ID obtained in the prerequisite step. | :::info Want to learn more? To learn more about the configurable properties, see the [Push notifications](/docs/mobile-identity/encap/server/manual/application-configuration/#push-notifications) section in our **Application configuration** documentation. ::: ### Configure the mobile SDK You must also configure the SDK for push notifications. To learn how to do this, read the platform-specific documentation using the buttons below: * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/push-notifications): Learn how to configure the Android SDK for push notifications * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications): Learn how to configure the iOS SDK for push notifications --- ## Reactivation ## About reactivation Previously there was no way to recover an end-user if they ended up in a state where they could no longer use their credentials on a device, or if the app was reinstalled. With our reactivation feature, end-users can reactivate and create new credentials on the same registration ID, given that they are still using the same device as they were originally activated on. This removes complexity, allowing the service provider to reuse the registration ID instead of creating a new one. ## How does reactivation work? Reactivate is similar to the normal activation flow, but with two exceptions: - The initiator has to be the service provider and is required to provide the device ID in the REST API start request. - The Encap server will compare the device hash stored on the registration with the device hash provided from the device to verify that it is the same device that is being activated. In a reactivation flow, all credentials previously stored on the registration get invalidated and need to be recreated. This can be done in the reactivation request and by activating additional activation methods to your registration. Sequence diagram showing reactivation ## Integration In order to reactivate a device, a service provider uses the same REST API as for a new activation, and is required to include the `device_id` parameter. The `application_id` parameter is optional in this use case, since it can be derived from the registration with the `device_id`. :::tip note For more details on how to initiate a reactivation, you can refer to the API documentation ::: ## Limitations - Reactivation does not work on registrations that have been deactivated by either the service provider or by the end-user. In these scenarios, the end-user needs to start a new activation. - The end-user must be on the same device. Encap validates the device hash during the reactivation to confirm that the end-user is still using the same device. Generally, the device hash will remain unchanged after a re-installation of the app, but we have identified the following exceptions: - Android: - Factory reset may change the device hash. - Reinstalling the app after an upgrade **from** Android version 7 or below **to** Android version 8 or above will cause changes to the device hash. - The device hash will not be carried over to a new device. - iOS: - Reinstalling the app from a non-encrypted backup after a factory reset. - The device hash will not be carried over to a new device. --- ## How it works(Encap) Our MFA solution uses a combination of something the end-user **has**, such as a mobile device, with either: - Something the user **knows**, such as a PIN. - Something the user **is**, such as biometrics. For example, this could be fingerprint or facial recognition. ## Integrate with Encap SCA To integrate with Encap SCA, there are two aspects that you need to consider: - **Encap server**: This is deployed in your infrastructure and exposes all operations through REST APIs. - **Mobile SDK**: This is integrated into your own mobile app, giving you complete control over the end-user journey and experience. We have an SDK for both Android and iOS. Diagram showing integration with Encap SCA using the SDK --- ## Encap SCA Encap SCA lets you authenticate and authorise end-user operations securely with your mobile app. It is our on-prem Strong Customer Authentication (SCA) mobile product that uses multi-factor authentication (MFA) to verify that the authorised end-user is the person making the transaction, not an unauthorised third party such as a hacker or fraudster. ## About Encap SCA - It allows you to achieve two-factor authentication by combining on-device biometrics or a PIN with the device itself. - It supports omni-channel transactions, meaning the transaction is always approved by your customer in your mobile app, regardless of what channel the transaction was initiated in. - It offers many additional features such as account recovery, app attestation and geofencing. - It is fully PSD2-compliant and supports Strong Customer Authentication (SCA), making it suitable for financial services, regulated industries and high-trust use cases. - It works the same way across all countries, making it ideal for businesses operating in multiple markets. ### Compliance Encap SCA is compliant with both: - [Payment Services Directive (PSD2)](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2) - [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/) ### Security Encap SCA has a layered security strategy. This means that we regularly add new layers of security to ensure that our product keeps up with the threat landscape. Our security features can help you prevent and reduce fraud by protecting against various types of mobile attacks, including: :::CustomTable{tableName="Encap SCA security features" columnWidths="25% 75%"} | **Attack** | **Description** | | :-- | :-- | | Man-in-the-middle (MITM) attacks | Encap SCA provides multiple layers of security to prevent a hacker from intercepting the communication between the mobile app and the backend system. For example, we use end-to-end encryption (E2EE) and an operation context to prevent unauthorised access. | | Phishing attacks | Phishing attacks where the end-user is tricked into giving away their credentials are becoming more frequent. Encap SCA can help prevent these types of attacks by using server-side biometrics and an operation context to verify the user and prevent unauthorised access. | | Device cloning | Cloning a device can give an attacker access to all of the end-user's installed apps, including mobile banking apps. Encap SCA uses hardware-protected keys and dynamically generated authentication keys to detect if a device is a clone. If a cloned device is detected, all operations on that device are rejected. | ::: ## Get started * [**Demo**](https://portal.encapsecurity.com/): Learn how Encap SCA works using our demo portal * [**Use cases**](/docs/mobile-identity/encap/use-cases/): Get inspired by how you can use Encap SCA in different use cases * [**How it works**](/docs/mobile-identity/encap/how-it-works): Learn about how Encap SCA works * [**Features**](/docs/mobile-identity/encap/features/): Learn about Encap SCA features in our feature guides ## Releases and upgrades * [**Release notes**](/docs/mobile-identity/encap/release-notes): View Encap SCA release notes * [**Documentation archive**](/docs/mobile-identity/encap/archive/): Browse the documentation for previous Encap SCA releases ## Support * [**SDK error codes**](/docs/mobile-identity/encap/sdk-error-codes): View the SDK error codes for Encap SCA --- ## Release notes To view the release notes, make a selection using the buttons below: * [**Android SDK**](/docs/mobile-identity/encap/release-notes/sdk-android): View the version release notes for our Android SDK * [**iOS SDK**](/docs/mobile-identity/encap/release-notes/sdk-ios): View the version release notes for our iOS SDK --- ## Android SDK :::info Follow the version release notes on this page for an overview of what is new in all of our supported SDK versions for Android. ::: ## SDK 3.22 :::warning Important Currently, only Encap SCA customers can upgrade to version 3.22 of our SDK. MobileID customers will be able to upgrade soon; we will keep you informed when this is possible. ::: **News for release:** SDK 3.22 - Improved security for compliance with NSM/NIST: - End-to-end encryption algorithms changed to X25519 and AES-GCM. Old elliptic curve keys will not work with 3.22 API. Set the `publicKeyBase64` property of the `EncapConfig` to the Base64-encoded DER X25519 public key. - Increased salt encryption key length to 32 and changed algorithm to AES-CTR. No changes in the Android SDK interfaces. - Added new feature **Device groups**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-android/configure-features/device-groups.mdx). - Added new error code `serverErrorMissingAuthMethod` that may occur if an authentication method in a device group is deactivated. - ANR prevention: - Added new non-blocking methods accepting a callback for support methods `activatedAuthMethods`, `activatedRecoveryMethods`, `isActivated`, `isRecoveryActivated`, and `registrationId`. - Changed initialisation of the controller to run on a background thread, to reduce the time used when creating the controller, and preventing Application Not Responding (ANR) situations. The app must check that the [controller state](/docs/mobile-identity/encap/sdk-android/appendix/controller-state.mdx) is `READY` or `ERROR_INITIALIZING` before attempting to do any operations such as `isActivated` on the controller. - Added a new `Controller.State` called `ERROR_INITIALIZING`, for when initialisation of the controller fails. - Removed all `Offline` authentication. - Removed error code `clientErrorOfflineVersionNotSupported` and `clientErrorOfflineParsingFailed`. ## SDK 3.21 **News for release:** SDK 3.21 - Added new risk parameters `SSID`, `BSSID`, `Barometer`, `Gravity`, `Magnetometer`, `IsDeveloperMode`, `IsOverlayDetected`, `IsProxyEnabled`, `IsVpnEnabled`, `Locale`. :::warning Set SSID/BSSID permissions If you enable the SSID and/or BSSID risk parameters, then you need to set up the necessary permissions in your `AndroidManifest.xml` file. To learn how to do this, see [Wi-Fi information (SSID and BSSID)](/docs/mobile-identity/encap/sdk-android/configure-features/risk-parameters/#wi-fi-information-ssid-and-bssid) in our **Risk parameters** feature documentation. ::: - For Recovery, renamed enum entry `RecoveryMethod.CLOUD_BACKUP` to `RecoveryMethod.CLOUD_BACKUP_RECOVERY_CODE`. :::danger Breaking change This is a breaking change. Replace any occurrences of `RecoveryMethod.CLOUD_BACKUP` with `RecoveryMethod.CLOUD_BACKUP_RECOVERY_CODE` in your code. ::: - To align with iOS, Android now returns error code `clientErrorAuthMethodUnavailable` instead of `clientErrorAuthMethodNotAllowed` in cases where biometrics are not enrolled on the device. :::note Note `clientErrorAuthMethodNotAllowed` is still returned in cases where an authentication method is being used but is not yet activated, or if not enabled in the server configuration. ::: - Added error code `clientErrorClientDataInvalid`, which indicates that the provided client data in the start authentication operation is invalid for one of the following reasons: - It exceeds the maximum size of 1024 bytes (UTF-8 encoded). - It contains one or more 4-byte UTF-8 characters (this includes most emojis, such as :+1:). - For error handling, added the exception class to each entry in the `ErrorCode`, so that the developer can look up the exception class for each error code. - Removed SDK error code `serverErrorAuthenticationRequired`. ## SDK 3.20 **News for release:** SDK 3.20 - Updated minimum Android version to Android 9 (API 28). - Encap Android API rewritten from Java to Kotlin 2.0, backwards compatible with API 3.19. - This rewrite adds a new dependency to `kotlin-stdlib` version 2.0. - Added support for recovery using face scan, in addition to keeping recovery code. - Added classes: - `RecoveryParameter` - `RecoveryCodeRecoveryParameter` - `ServerSideFaceRecoveryParameter` - Added enum entry `RecoveryMethod.CLOUD_BACKUP_SERVER_SIDE_FACE`. - Added `Controller` methods accepting `RecoveryParameter`: - `fun finishAddOrUpdateRecovery(recoveryParameter: RecoveryParameter, appCallback: AsyncCallback)` - `fun finishRecovery(recoveryParameter: RecoveryParameter, activationParameter: ActivationParameter, appCallback: AsyncCallback)` - `fun finishDeleteRecovery(recoveryParameter: RecoveryParameter, appCallback: AsyncCallback)` - Deprecated class `EncapRecoveryParameter` and `Controller` methods accepting it. - Removed deprecated `Controller` methods: - `void startAddOrUpdate(String clientData, AsyncCallback callback);` - Removed SDK error code `serverErrorAlreadyAuthenticated`. - Removed SDK error code `clientErrorGoogleServicesOutdated` and `GooglePlayServicesOutdatedException`. ## SDK 3.19 **News for release:** SDK 3.19 - Updated minimum Android version to Android 8 (API 26). - The authentication method `AuthMethod.DEVICE_ANDROID_FINGERPRINT` is removed completely. Use `AuthMethod.DEVICE_ANDROID_BIOMETRIC_PROMPT` instead. Users that are already using Fingerprint can migrate from Pin to Biometric using addOrUpdate. To migrate from Fingerprint to Biometric an earlier version of the SDK needs to be used. - Added new authentication method `AuthMethod.DEVICE_SERVER_SIDE_FACE`. :::tip What is the use case? The current primary use case is to change the PIN when the end-user has forgotten it and has no valid biometrics. ::: - Added new `Controller` methods: - `void startAddOrUpdate(@NonNull StartAddOrUpdateParameter startParameter, @NonNull AsyncCallback callback);` :::tip Note - For use with server-side face only, use start calls with `StartAddOrUpdateParameter(AuthMethod.DEVICE_SERVER_SIDE_FACE)`. - For use with `clientData`, use start calls with `StartAddOrUpdateParameter(String clientData)`. - Deprecated `Controller` methods: - `void startAddOrUpdate(String clientData, AsyncCallback callback);` :::tip Note The `String clientData` argument to the above method is made obsolete by the new method accepting `StartAddOrUpdateParameter(String clientData)` . ::: - If biometrics or fingerprint are not enrolled or enabled on the device, then return `BiometricAuthenticationException` with `clientErrorAndroidBiometricPromptErrorNoBiometrics`. This is instead of ```UnexpectedException``` with ```clientErrorUnexpected```. - Added @NonNull and @Nullable to all Controller methods, to ease interfacing with Kotlin. - `PROCESSING_DEACTIVATION` is now a blocking state. If a new operation is started before deactivation is finished, then a `clientErrorOperationInProgress` error is returned. ## SDK 3.18 **News for release:** SDK 3.18 - Documentation improvements: - Restructured to improve usability. - Multiple sections have been rewritten. - Added new examples which are easier to copy and paste. - Deprecated the **fingerprint** authentication method. This means that it will be removed in a future release. - Added the annotation `@NonNull` to both the `OnSuccess` and `OnFailure` functions of `AsyncCallback`. - Unified the operation context methods. This means that the following functions on result classes `FinishActivationResult` and `FinishAuthenticationResult` are renamed: :::CustomTable{columnWidths="50% 50%"} | Previous name | New name | | :-- | :-- | | `getResponseTitle()` | `getContextTitle()` | | `getResponseConent()` | `getContextContent()` | | `getResponseMimeType()` | `getContextMIME()` | ::: :::tip Note This matches the method names for `StartAuthenticationResult` and on iOS. The old methods are deprecated. They will be removed in the next release. ::: ## SDK 3.17 **News for release:** SDK 3.17 - Updated minimum Android version to Android 7. - **Safety Net attestation** is replaced with **Play Integrity**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-android/configure-features/app-attestation.mdx). - The two activation and authentication parameters for Biometric Prompt now expose `setConfirmationRequired()`. - Removed **Intermediate push feature**. You must use Play Integrity for app attestation instead. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-android/configure-features/app-attestation.mdx). - Removed deprecated API methods: :::CustomTable{columnWidths="50% 50%"} | Removed deprecated API method | Use instead | | :-- | :-- | | `StartAuthenticationResult`: `getAllowedAuthMethods()` | `getAuthMethodsForAuthentication()` | | `StartActivationResult`: `getAllowedAuthMethods()` | `getAuthMethodsForActivation()` | | `StartAddOrUpdateResult`: `getAllowedAuthMethodsForActivation()` | `getAuthMethodsForActivation()` | ::: ## SDK 3.16 **News for release:** SDK 3.16 - Added new feature Client debug data. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-android/configure-features/client-debug-data.mdx). - Added new `EncapConfig` setting `setAllowDebugData`. - This is set to true by default. - This can be set to false to reserve a device from sending debug data, even if it is turned on in your **Application configuration**. - Deactivating a non-activated registration on the client no longer results in an error. - Removed documentation about **fingerprint**. - For all new implementations, we recommend using Biometric Prompt. - If fingerprint is needed on Android versions 6-8, we recommend using Biometric Prompt with AndroidX library. - The removed fingerprint documentation can still be accessed in an older version of this document if needed. - Removed documentation about **How to build with Maven**. - The removed documentation about integration with Maven can still be accessed in an older version of this document if needed. - **SafetyNet** attestation will be replaced with **Play Integrity** in version 3.17. - Deprecated API methods: :::CustomTable{columnWidths="50% 50%"} | Deprecated API method | Use instead | | :-- | :-- | | `StartAuthenticationResult`: `getAllowedAuthMethods()` | `getAuthMethodsForAuthentication()` | | `StartActivationResult`: `getAllowedAuthMethods()` | `getAuthMethodsForActivation()` | | `StartAddOrUpdateResult`: `getAllowedAuthMethodsForActivation()` | `getAuthMethodsForActivation()` | ::: ## SDK 3.15 **News for release:** SDK 3.15 - Replaced error `clientErrorKeyPermanentlyInvalidated` with code `180`, with error `clientErrorAuthDataInvalidated` with code `132`. This is to match the iOS implementation. - Added support for cancelling an ongoing Biometric authentication for [AndroidX BiometricPrompt](https://developer.android.com/reference/androidx/biometric/package-summary). - The app can cancel an ongoing Biometric authentication by supplying a [`CancellationSignal`](https://developer.android.com/reference/android/os/CancellationSignal) to the `DeviceAndroidBiometricPromptAuthParameter`, and calling the [`cancel()`](https://developer.android.com/reference/android/os/CancellationSignal#cancel()) method. - For AndroidX BiometricPrompt, this is implemented so that the Encap API sets up a listener on the `CancellationSignal` that will call the `cancelAuthentication()` method of the AndroidX BiometricPrompt. - Deprecated **Intermediate Push** attestation. This will be removed in a future release. ## SDK 3.14 **News for release:** SDK 3.14 - Added new feature for **Geofencing**. In this feature, the SDK performs a lookup of the device location to an external Geocoder service and sends the country code to the server. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-android/configure-features/geofencing.mdx). - Changed name of `AuthenticateAndActivate` to `AddOrUpdate`. - On iOS, this function has always been called `AddOrUpdate`. Android is now changing to make the two controller interfaces look more similar. - Removed **Signing** feature. is removed. This means that these functions do not exist any more and you need to remove the use of it in your app: - `EncapConfig.Builder: setSigningEnabled(), setSigningKeySize()` - `EncapController: startAuthenticationOrSigning(), startSigning(), FinishSigning()` - `EncapController.State: isSigningState()` - `PushMessage: isSigningMessage()` - `SigningFailedException, StartSigningResult, FinishSigningResult` - Added new error code `serverErrorInvalidSession`. This means that if a new session is started on the server after the client has done `startAuthenticate`, then you will get this error during `finishAuthenticate`, and you need to do `startAuthenticate` again. - Removed error codes: - `serverErrorIncorrectSignature` - `serverErrorInvalidSignature` --- ## iOS SDK :::info Follow the version release notes on this page for an overview of what is new in all of our supported SDK versions for iOS. ::: ## SDK 3.22 :::warning Important Currently, only Encap SCA customers can upgrade to version 3.22 of our SDK. MobileID customers will be able to upgrade soon; we will keep you informed when this is possible. ::: **News for release:** SDK 3.22 - Improved security for compliance with NSM/NIST: - End-to-end encryption algorithms changed to X25519 and AES-GCM. Old elliptic curve keys will not work with 3.22 API. Set the `publicKey` property of the `EncapConfig` to the X25519 public key. - Increased salt encryption key length to 32 and changed algorithm to AES-CTR. - Added new feature **Device groups**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/device-groups.mdx). - Added error code `serverErrorMissingAuthMethod`, which indicates that the authentication method required for the operation is missing. - Removed all `Offline` authentication. - Removed error code `clientErrorOfflineVersionNotSupported`, `clientErrorOfflineParsingFailed` and `serverErrorClientOnlyDisallowed`. - Introduced API changes to enforce PSD2 (Payment Services Directive 2) compliance for secure credential handling. :::danger Breaking change For PSD2 compliance, the SDK's activation and authentication APIs now require `NSMutableString` for PIN, activation code, and recovery code parameters, rather than accepting `String` or `NSString`. This enforces credential handling that allows for secure memory overwriting immediately after use. The following parameters now accept `NSMutableString` instead of `String`: - `AuthMethod.pin(value:)` - `startActivationWithCode(_:)` - `RecoveryMethod.backupRecoveryCode(_:)` Any client passing a Swift `String` or `NSString` literal will receive a compiler error after updating to this version. To learn how to update your code, and for guidance on data classification and memory management, see our [Security best practices](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices) documentation. ::: ## SDK 3.21 **News for release:** SDK 3.21 - Minimum iOS version updated to 15.0. - Added new risk parameters `SSID`, `BSSID`, `Gravity`, `Magnetometer`, `IsProxyEnabled`, `IsVpnEnabled`, `timeZone`, `Locale`. :::warning Set SSID/BSSID permissions If you enable the SSID and/or BSSID risk parameters, then you must add the necessary entitlement to your application's target in Xcode. To learn how to do this, see [Wi-Fi information (SSID and BSSID)](/docs/mobile-identity/encap/sdk-ios/configure-features/risk-parameters/#wi-fi-information-ssid-and-bssid) in our **Risk parameters** feature documentation. ::: - For Recovery, renamed enum entry `RecoveryMethod.backup` to `RecoveryMethod.backupRecoveryCode`. :::danger Breaking change This is a breaking change. Replace any occurrences of `RecoveryMethod.backup` with `RecoveryMethod.backupRecoveryCode` in your code. ::: - Unified the error returned when an authentication method is deactivated locally due to invalidation. Previously `clientErrorAuthMethodUnavailable` was returned. Now `clientErrorAuthMethodNotAllowed` is used, to align with Android behaviour. - Added error code `clientErrorClientDataInvalid`, which indicates that the provided client data in the start authentication operation is invalid for one of the following reasons: - It exceeds the maximum size of 1024 bytes (UTF-8 encoded). - It contains one or more 4-byte UTF-8 characters (this includes most emojis, such as :+1:). - Removed SDK error code `serverErrorAuthenticationRequired`. ## SDK 3.20 **News for release:** SDK 3.20 - Added new `RecoveryMethod` for face scan `RecoveryMethod.backupServerSideFace(faceScanData: FaceScanData)`. - Added optional field `serverSideFaceInit: ServerSideFaceInitResult?` into `startRecoveryResult`. - Added new `EncapConfig` property `locationEnabled`. :::info Want to learn more? To learn more, see our [Location](/docs/mobile-identity/encap/sdk-ios/configure-features/location.mdx) feature documentation. ::: - Removed EncapAPI (Objective-C version). :::warning Important If you are still using this API, then you must start using EncapSwiftAPI instead. ::: - Removed error codes `serverErrorAlreadyAuthenticated` and `serverErrorExpiredSession`. ## SDK 3.19 **News for release:** SDK 3.19 - Updated minimum iOS version to 14.0. - Added new `AuthMethod` for face scan `AuthMethod.serverSideFace(faceScanData: FaceScanData?)`. :::info What does this mean? This new authentication method has the current primary use case of activating a registration in situations where the end-user has forgotten their PIN and has no valid biometrics. ::: - Added new `EncapController` methods `startAddOrUpdate(startAddOrUpdateParameter: StartAddOrUpdateParameter)`: - For use with Server-side face only, use start calls with `StartAddOrUpdateParameter(selectedAuthMethod: .serverSideFace(faceScanData: FaceScanData()))`. - For use with `clientData`, use start calls with `StartAddOrUpdateParameter(clientData: String)`. - Removed `EncapPushDelegate`. - Removed support for weak hashing algorithms, such as `MD4`, `MD5` and `SHA-1`. - Removed support for methods: - `initWithDelegate` - `didFinishLaunchingWithOptions` - `didReceiveRemoteNotification` - Deprecated `startAddOrUpdate(clientData: String)`. - Removed support for authentication method `AuthMethod.touchID`. Use `AuthMethod.strongTouchID` instead. ## SDK 3.18 **News for release:** SDK 3.18 - Documentation improvements: - Restructured to improve usability. - Multiple sections have been rewritten. - Added new examples which are easier to copy and paste. - Removed error code `serverErrorAppAttestValidationFailed`. If validation of App Attest fails, then `serverErrorIncorrectResponse` is returned. ## SDK 3.17 **News for release:** SDK 3.17 - `EncapAPI` and `EncapSwiftAPI` are no longer built with bitcode. - Removed **Intermediate Push** feature. - Removed deprecated `availableAuthMethods`. ## SDK 3.16 **News for release:** SDK 3.16 - Minimum iOS version updated to 12.0. - Added new feature **Client debug data**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/client-debug-data.mdx). - Added support for **Time Sensitive Notifications**, You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications.mdx#customise-the-push-message). - Added new feature to support **Apple App extensions**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/extension-support.mdx). - Deprecated `availableAuthMethods`. Use `authMethodsForActivation` and `authMethodsForAuthentication` instead. - Deprecated `EncapDeviceTouchIDAuthParameter` and `EncapAuthMethodDeviceTouchID`. Use `EncapAuthMethodDeviceStrongTouchID` instead. ## SDK 3.15 **News for release:** SDK 3.15 - Added support for arm64-simulator architecture. - Added new feature for **App attestation**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/app-attestation.mdx). - Simplified push handling with `handleNotification()`. You can learn more in our **Push** [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications.mdx). ## SDK 3.14 **News for release:** SDK 3.14 - Minimum iOS version updated to 11.0. - Added new feature for **Geofencing**. You can learn more in our [feature documentation](/docs/mobile-identity/encap/sdk-ios/configure-features/geofencing.mdx). - All builds contain bitcode. - `encap-ios-api-obfuscated` version is no longer available. - Removed **Signing** feature. ## SDK 3.13 **News for release:** SDK 3.13 - Minimum iOS version updated to 10.0. - Added `APNS_NOTIFICATION_SOUND_ENABLED` to **Application configuration**. If enabled, then the default sound is added to APS payload. - `EncapToken` is used for tokenised operations. - Added support for recovering the registration by using iCloud or computer-based backup. --- ## Back up and restore attributes :::warning Important You should not back up or restore Encap SCA data. ::: ## How does file exclusion work? 1. We list all files that should be excluded in a file in the Encap library: ```xml title="Example: File containing list of exclusions in Encap library" ``` 2. The Encap library automatically adds excluded files into the `AndroidManifest.xml` file. This means that no action is required by you if `allowBackup` is turned on or off. 3. If you need to make any selective exclusions inside of your app, then you can do this by overriding the content inside of your app's `AndroidManifest.xml` file. ```xml title="Example: Override content inside AndroidManifest.xml" // for apps targeting and running on API >= 31 ``` ### Apps running API 31 and above For apps running and targeting API 31 and above: - You need to include `android:dataExtractionRules`. - The old configuration `android:fullBackupContent` is still required for devices running Android 11 or lower. - You need to include the files below in the `new_backup_rules.xml` and `new_backup_data_extraction_rules.xml` files: ```xml title="Example: Files to include in new_backup_rules.xml" ``` ```xml title="Example: Files to include in new_backup_data_extraction_rules.xml" ``` ### Apps using FCM If your application uses Firebase Cloud Messaging (FCM), then you should also exclude the `com.google.android.gms.appid.xml` file that contains the FCM registration ID from backup. ## Restoring on a new device If Encap data is backed up to one device and then restored on another device, then the Encap API is not able to decrypt the data restored on the second device correctly. :::info Want to learn more? To learn more about Android backup and restore, see the [Android developer documentation](https://developer.android.com/identity/data/backup). ::: --- ## Controller state The controller contains a state of the ongoing operation, which is propagated though the state change interface `onStateChanged(...)`. ```kotlin title="Example: State of ongoing operation" interface AsyncStateChangedCallback { fun onStateChanged(state: EncapController.State) } ``` ```java title="Example: State of ongoing operation" interface AsyncStateChangedCallback { void onStateChanged(EncapController.State state) } ``` ## Controller states To learn about the possible states for each ongoing operation, see the tables in the sections below. ### Initialisation states The table below shows a list of possible states involved during initialisation. :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `INITIALIZING` | State indicating that the controller has been created and is initialising in the background. Attempted operations such as `isActivated` or similar will fail. | | `READY` | State indicating that the controller has successfully initialised and is ready to be used. | | `ERROR_INITIALIZING` | State indicating that the controller failed to initialise. attempted operations will return the `ErrorCodeException`, which contains details of the failure. | ::: ### Activation states The table below shows a list of possible states which indicate that the controller is performing an activation, or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `AWAITING_START_ACTIVATION` | State indicating that the controller is ready for the `startActivation` call. | | `PROCESSING_START_ACTIVATION` | State present from the `startActivation` call until when callback returns the result. | | `AWAITING_FINISH_ACTIVATION` | State indicating that the controller is ready for the `finishActivation` call. | | `PROCESSING_AUTH_METHOD_ACTIVATION` | State present from when the `finishActivation` call is triggered until when the `authMethod` is validated. In the case of biometrics, it lasts until the end-user confirms the prompt. In the case of PIN, it happens almost instantly. | | `PROCESSING_FINISH_ACTIVATION` | State present from after the `authMethod` validation until the full operation is completed. | | `FINISHED_ACTIVATION` | State indicating that the operation was successful. | | `ERROR_ACTIVATION` | State indicating that there was an error during activation. | ::: ### Authentication states The table below shows a list of possible states which indicate that the controller is performing an authentication, or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_AUTHENTICATION` | State present from the `startAuthentication` call until when callback returns the result. | | `AWAITING_FINISH_AUTHENTICATION` | State indicating that the controller is ready for the `finishAuthentication` call. | | `PROCESSING_AUTH_METHOD_AUTHENTICATION` | State present from when the `finishAuthentication` call is triggered until when the `authMethod` is validated. In the case of biometrics, it lasts until the end-user confirms the prompt. In the case of PIN, it happens almost instantly. | | `PROCESSING_FINISH_AUTHENTICATION` | State present from after the `authMethod` validation until the full operation is completed. | | `FINISHED_AUTHENTICATION` | State indicating that the operation was successful. | | `ERROR_AUTHENTICATION` | State indicating that there was an error during authentication. | ::: ### Add or update states The table below shows a list of possible states which indicate that the controller is performing an add or update, or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_ADD_OR_UPDATE` | State present from the `startAddOrUpdate` call until when callback returns the result. | | `AWAITING_FINISH_ADD_OR_UPDATE` | State indicating that the controller is ready for the `finishAddOrUpdate` call. | | `PROCESSING_AUTH_METHOD_ADD_OR_UPDATE` | State present from when the `finishAddOrUpdate` call is triggered until when the `authMethod` is validated. In the case of biometrics, it lasts until the end-user confirms the prompt. In the case of PIN, it happens almost instantly. | | `PROCESSING_FINISH_ADD_OR_UPDATE` | State present from after the `authMethod` validation until the full operation is completed. | | `FINISHED_ADD_OR_UPDATE` | State indicating that the operation was successful. | | `ERROR_ADD_OR_UPDATE` | State indicating that there was an error during add or update. | ::: ### Deactivation states The table below shows a list of possible states which indicate that the controller is performing a deactivation, or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_DEACTIVATION` | State present from the `deactivate` call until the device authentication is successful. **Note**: This is only applicable when using the `deactivate()` method with parameter `localOnly` set to `false`. | | `PROCESSING_FINISH_DEACTIVATION` | State present from either: A successful device authentication, until the deactivation operation is completed. The `deactivate` call if `localOnly` is set to `true`, until the deactivation operation is completed. | | `FINISHED_DEACTIVATION` | State indicating that the operation was successful. | | `ERROR_DEACTIVATION` | State indicating that there was an error during deactivation. | ::: :::tip States returned during deactivation When using the deactivation method `deactivate()` with parameter `localOnly` set to `false`, a device authentication happens towards the server. This means that during deactivation, the state also contains values shown in the [Authentication states](#authentication-states) section. ::: ### Adding a recovery states The table below shows a list of possible states which indicate that the controller is adding a recovery, or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_ADD_OR_UPDATE_RECOVERY` | State present from the `startAddOrUpdateRecovery` call until when callback returns the result. | | `AWAITING_FINISH_ADD_OR_UPDATE_RECOVERY` | State indicating that the controller is ready for the `finishAddOrUpdateRecovery` call. | | `PROCESSING_FINISH_ADD_OR_UPDATE_RECOVERY` | State present from after the `authMethod` is validated until the full operation is completed. | | `FINISHED_ADD_OR_UPDATE_RECOVERY` | State indicating that the operation was successful. | | `ERROR_ADD_OR_UPDATE_RECOVERY` | State indicating that there was an error during adding a recovery. | ::: ### Performing a recovery states The table below shows a list of possible states which indicate that the controller is performing a recovery or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_RECOVERY` | State present from the `startRecovery` call until when callback returns the result. | | `AWAITING_FINISH_RECOVERY` | State indicating that the controller is ready for the `finishRecovery` call. | | `PROCESSING_AUTH_METHOD_RECOVERY` | State present from when the `finishRecovery` call is triggered until when the `authMethod` is validated. In the case of biometrics, it lasts until the end-user confirms the prompt. In the case of PIN, it happens almost instantly. | | `PROCESSING_FINISH_RECOVERY` | State present from after the `authMethod` is validated until the full operation is completed. | | `FINISHED_RECOVERY` | State indicating that the operation was successful. | | `ERROR_RECOVERY` | State indicating that there was an error during performing a recovery. | ::: ### Deleting a recovery states The table below shows a list of possible states which indicate that the controller is deleting a recovery or is ready to start it: :::CustomTable{columnWidths="40% 60%"} | **State** | **Description** | | :-- | :-- | | `PROCESSING_START_DELETE_RECOVERY` | State present from the `startDeleteRecovery` call until when callback returns the result. | | `AWAITING_FINISH_DELETE_RECOVERY` | State indicating that the controller is ready for the `finishDeleteRecovery` call. | | `PROCESSING_FINISH_DELETE_RECOVERY` | State present from after the `authMethod` is validated until the full operation is completed. | | `FINISHED_DELETE_RECOVERY` | State indicating that the operation was successful. | | `ERROR_DELETE_RECOVERY` | State indicating that there was an error during deleting a recovery. | ::: ## Blocking states Blocking states indicate that there is an operation that has to be finished first. The table below shows a list of states that block other operations: :::CustomTable{columnWidths="30% 35% 35%"} | **State** | **Blocking description** | **State description** | | :-- | :-- | :-- | | `INITIALIZING` | The blocking state during creation of the controller. | | | `PROCESSING_CANCEL_SESSION` | The blocking state whilst the cancel operation is in progress. | | | `PROCESSING_LOAD_CONFIG` | The blocking state whilst the load configuration operation is in progress. | | | `PROCESSING_START_ACTIVATION` | The blocking state whilst the start activation operation is in progress. |[Activation states](#activation-states) | | `PROCESSING_FINISH_ACTIVATION`| The blocking state whilst the finish activation operation is in progress. | [Activation states](#activation-states) | | `PROCESSING_AUTH_METHOD_ACTIVATION`| The blocking state whilst the `authMethod` is validated. | [Activation states](#activation-states) | | `PROCESSING_START_DEACTIVATION` | The blocking state whilst the start deactivation operation is in progress. | [Deactivation states](#deactivation-states) | | `PROCESSING_FINISH_DEACTIVATION` | The blocking state whilst the finish deactivation operation is in progress. | [Deactivation states](#deactivation-states) | | `PROCESSING_START_AUTHENTICATION` | The blocking state whilst the start authentication operation is in progress. | [Authentication states](#authentication-states) | | `PROCESSING_FINISH_AUTHENTICATION` | The blocking state whilst the finish authentication operation is in progress. | [Authentication states](#authentication-states) | | `PROCESSING_AUTH_METHOD_AUTHENTICATION`| The blocking state whilst the `authMethod` is validated. | [Authentication states](#authentication-states) | | `PROCESSING_START_ADD_OR_UPDATE` | The blocking state whilst the start add or update operation is in progress. | [Add or update states](#add-or-update-states) | | `PROCESSING_FINISH_ADD_OR_UPDATE` | The blocking state whilst the finish add or update operation is in progress. | [Add or update states](#add-or-update-states) | | `PROCESSING_AUTH_METHOD_ADD_OR_UPDATE`| The blocking state whilst the `authMethod` is validated. | [Add or update states](#add-or-updatestates) | | `PROCESSING_START_ADD_OR_UPDATE_RECOVERY` | The blocking state whilst the start add or update recovery operation is in progress. | [Adding a recovery states](#adding-a-recovery-states) | | `PROCESSING_FINISH_ADD_OR_UPDATE_RECOVERY` | The blocking state whilst the finish add or update recovery operation is in progress. | [Adding a recovery states](#adding-a-recovery-states) | | `PROCESSING_START_RECOVERY` | The blocking state whilst the start recovery operation is in progress. | [Performing a recovery states](#performing-a-recovery-states) | | `PROCESSING_AUTH_METHOD_RECOVERY` | The blocking state whilst the authentication method recovery operation is in progress. | [Performing a recovery states](#performing-a-recovery-states) | | `PROCESSING_FINISH_RECOVERY` | The blocking state whilst the finish recovery operation is in progress. | [Performing a recovery states](#performing-a-recovery-states) | | `PROCESSING_START_DELETE_RECOVERY` | The blocking state whilst the start delete recovery operation is in progress. | [Deleting a recovery states](#deleting-a-recovery-states) | | `PROCESSING_FINISH_DELETE_RECOVERY` | The blocking state whilst the finish delete recovery operation is in progress. | [Deleting a recovery states](#deleting-a-recovery-states) | ::: --- ## Device hash ## About the device hash The device hash is a SHA256 hash of a universally unique identifier (UUID) derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. - In Android 8.0 and above, the `ANDROID_ID` is a unique value to each device, user and signing key. - In versions prior to Android 8.0, the `ANDROID_ID` is generated during device setup and is constant for the lifetime of the device. - If an end-user updates their system from a version prior to Android 8.0 to a version of Android 8.0 or above, then the `ANDROID_ID` could change for an app if the app is uninstalled and installed again. :::info Want to learn more? You can find more information about this in the [Android developer documentation](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). ::: ### When is the device hash deleted? The device ID (`deviceId`) may change if a factory reset is performed on the device. ### Device hash details - The `deviceHash` = SHA256(`UUID.nameUUIDFromBytes(deviceId.getBytes()).toString())`) - The `deviceId` = `Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID)` --- ## Error handling ## About error handling Every operation on the `Controller` takes a callback with a success and a failure method. When an operation fails, an `ErrorCodeException` object is passed as a parameter to `onFailure`. This object contains important information that the app can use to determine how to continue the flow. It can also be used to help guide the end-user on how to resolve the issue. In a production app, logging the right error information when errors occur can play a crucial role in finding bugs. It can also assist with corner cases that would otherwise be difficult to find and solve without the log. ## How does error handling work? The `ErrorCodeException` object contains the following methods: :::CustomTable{columnWidths="25% 50% 25%" minTableSize="900px"} | **Method** | **Description** | **Example** | | :-- | :-- | :-- | | `getErrorCode()` | Returns an `ErrorCode` enum object that identifies the type of error. **Note**: For more details, see the [Error code enum object](#error-code-enum-object) table below. | `ErrorCode.clientErrorNotActivated` | | `getMessage` | Returns a technical description of the error. This can help you to determine what went wrong. | `Not activated` | | `getCause()` | Returns the exception that caused this exception, if applicable. **Note**: This can be nested in several layers. In the case of the first exception, this will return null. | `IOException()` | | `isRecoverableError()` | A boolean that indicates whether the error is final, or if it is possible to retry in a finish operation. | `true` | | `getRemainingAttempts()` | Indicates how remaining attempts the end-user has to perform an authentication. After this, a failure will result in their registration being locked by the Encap server. **Note**: This function only exists if the object type is `AuthenticationFailedException`. | `3` | ::: :::note Note For any server-related errors in production, `getMessage()` will return the following: ``` Error description not available in production. ``` ::: :::note Obtaining additional information You may be able to obtain additional information that can be used during development by using the `toString()` method of the `ErrorCodeException`. ::: ### Error code enum object The `ErrorCode` enum object contains the following methods: :::CustomTable{columnWidths="33% 33% 33%"} | **Method** | **Description** | **Example** | | :-- | :-- | :-- | | `getErrorCodeName()` | Returns the name of the error code. | `clientErrorNotActivated` | | `getErrorCodeNumber()` | Returns the number of the error code. | `106` | ::: ## Recoverable errors Most Encap operations are divided into a start and finish call. Typically, if a finish call fails, then the app must restart the process with a new start call before attempting the finish call again. However, in some cases, the app can retry the finish call directly without having to do this. To determine whether this is possible, you can check the return value of the property `isRecoverableError()`: - If `true`, then the app or end-user can retry the same finish call without restarting the flow. - If `false`, then the app must restart the process with a new start call before attempting the finish call again. :::info Example For example, the error `clientErrorInvalidInputFormat` allows the app to retry the same finish call without restarting the flow. ::: ### Limited retries Certain types of recoverable errors may only have a limited amount of retries, such as when an incorrect PIN is entered. In these cases, `isRecoverableError()` will still return `true`, but the error object will include details about how many more retry attempts are allowed. :::note Note On Android, this happens when the `ErrorCodeException` is of type `AuthenticationFailedException`. The type needs to be cast before being queried for information. ::: You can access the remaining attempts using `getRemainingAttempts()`. This can be valuable for the end-user to know before they retry with a new PIN. For a full list of recoverable errors, see the [Recoverable errors](/docs/mobile-identity/encap/sdk-error-codes/#recoverable-errors) section on the SDK error codes page. ## Logging errors We recommend that you implement proper error logging procedures, so that you can obtain valuable information about errors when they occur. This information allows us to identify and resolve the issue faster when you report it to us. The most valuable details you can provide us are: - The `errorCode.getErrorCodeName()`. - The `exception.getMessage()`. - The type of the `exception exception.getClass().getName()`. - The stack `exception.printStackTrace(...)`. :::note Note You need to loop through all `getCause()exceptions` to get the full stack. Ensure that you save the `.map` file when building, so that it is possible to deobfuscate the stack. ::: - The Encap operation the error occurred in. - The version of the Encap SDK and server being used. - The version of Android being used. :::tip Tip Many logging tools also make it possible to follow the order of SDK operations performed by the app. This can be valuable for recreating certain errors that are otherwise difficult to reproduce. ::: --- ## Example project ## About the example project The Encap SCA client SDK for Android is available for download from our repository. It comes with a standalone example project and installable app to demonstrate the use of the API. The repository is gated, therefore you require login credentials to access it. ## Get started :::tip Need access To get your login credentials, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: 1. Request your Nexus repository login credentials from us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. 2. Navigate to our repository and enter your Nexus repository login credentials. Browse for the correct version of the ZIP file in our repository, then download and unzip it. Alternatively, you can download and install the APK file: - Link for [MobileID customers](https://nexus.pub.encap.no/#browse/browse:MobileID-partner:com%2Fencapsecurity%2Fencap-example-android-testapp). - Link for [Encap SCA customers](https://nexus.pub.encap.no/#browse/browse:encap-partner-releases:com%2Fencapsecurity%2Fencap-example-android-testapp). 3. Run the project or the app. 4. Set the `serverURL`. - For MobileID customers, use `https://api.signicat.com/encore/encap`. - For Encap SCA customers, use the URL for your Encap SCA server. --- ## Appendices You can learn about frequently asked questions, corner cases and recommendations in our appendices. * [**Back up and restore attributes**](/docs/mobile-identity/encap/sdk-android/appendix/back-up-restore-attributes): Learn how to handle back up and restore for Encap SCA * [**Controller state**](/docs/mobile-identity/encap/sdk-android/appendix/controller-state): Read about the different states for an Encap controller * [**Device hash**](/docs/mobile-identity/encap/sdk-android/appendix/device-hash): Learn about the device hash * [**Error handling**](/docs/mobile-identity/encap/sdk-android/appendix/error-handling): Learn how to handle errors * [**Example project**](/docs/mobile-identity/encap/sdk-android/appendix/example-project): Use our example project to quickly get started with the Encap Android SDK * [**Known problems**](/docs/mobile-identity/encap/sdk-android/appendix/known-problems): An overview of known problems on specific Android devices * [**Security best practices**](/docs/mobile-identity/encap/sdk-android/appendix/security-best-practices): Learn how to manage sensitive data and ensure PSD2 compliance * [**Stack trace**](/docs/mobile-identity/encap/sdk-android/appendix/stack-trace): Learn how to retrace a stack trace with obfuscated data * [**Thread handling**](/docs/mobile-identity/encap/sdk-android/appendix/thread-handling): Learn how to handle threads * [**Version errors**](/docs/mobile-identity/encap/sdk-android/appendix/version-errors): Learn how to handle errors related to SDK versions :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Known problems ## About known problems This appendix provides you with an overview of known problems with Encap SCA, for specific Android devices. ## Overview :::CustomTable | **Feature** | **Phone** | **Android version** | **Issue** | | :-- | :-- | :-- | :-- | | `setSingleBiometricPromptEnabled` | ZTE Axon | 8.0 | If this feature is used on this mobile device, then the second activation will return the error code `clientErrorKeyUserNotAuthenticated`. | | `clientErrorAuthDataInvalidated` | All | 8.0 | For this version of Android, if a new fingerprint is added on the mobile device after a fingerprint has been registered in the app, then it will not return the error code `clientErrorAuthDataInvalidated`. | ::: --- ## Security best practices To maintain compliance with PSD2 (Payment Services Directive 2) and ensure robust application security, it is important that you properly manage how sensitive data is handled in memory. On this page, you can learn about: - The different types of data handled by the SDK. - The classification of data handled by the SDK. - How you should manage data in your application's memory lifecycle. ## How does it work? When handling authentication and user verification, sensitive data is temporarily loaded into the mobile device's memory. To prevent this data from being exposed in the event of a memory dump or a device-level compromise, we recommend that you overwrite secrets as early as possible after use, so that they are completely erased from memory. ### Classification definitions To learn about the different data classifications, see the table below: | **Classification** | **Description** | | :-- | :-- | | `SECRET` | This data is highly sensitive.

You should overwrite it in memory immediately after it is no longer required. | | `NOT SECRET` | This data is not considered highly sensitive.

You do not need to overwrite it after use, although doing so is safe and acceptable. | ## Data classification and handling You can learn about the specific data types, their security classification, and the reasoning behind their memory management requirements in the tables below. ### User inputs and codes :::CustomTable{columnWidths="20% 20% 60%"} | **Data type** | **Classification** | **Memory management** | | :-- | :-- | :-- | | PIN | `SECRET` | The end-user's PIN must not be stored anywhere. It should be overwritten immediately after it is sent to the controller and no longer needed. | | Activation code | `SECRET` | This is a one-time code that could potentially be copied and used as long as the session remains valid (typically a maximum of 5 minutes). It must be erased from memory right after the activation is triggered. | | Recovery code | `SECRET` | The recovery code is similar to a PIN in terms of its validity lifecycle. It must be overwritten as soon as the recovery process is successfully initiated or rejected. | ::: ### Token authorisation :::CustomTable{columnWidths="20% 20% 60%"} | **Data type** | **Classification** | **Memory management** | | :-- | :-- | :-- | | Token ID | `NOT SECRET` | The token ID is a hash that is only valid for the specific application on the device during recovery operations. Because the authorisation token cannot be utilised outside of this specific context, it does not strictly need to be overwritten. | ::: :::info Want to learn more? To learn how the authorisation token is used for recovery operations, see the Android [Account recovery](/docs/mobile-identity/encap/sdk-android/configure-features/account-recovery#token-authorisation) feature documentation. ::: ## Memory management in Java and Kotlin When handling `SECRET` data in Java or Kotlin, you should not store the values as `String` objects. This is because strings are immutable in the JVM, which leaves the sensitive data vulnerable to memory dumping and analysis. :::note What does this mean? Once a `String` is created, its value cannot be modified or overwritten; it remains in memory until the Garbage Collector unpredictably decides to clean it up. ::: Instead of strings, you should always use mutable data structures to store sensitive information. For example: - `CharArray` - `ByteArray` This allows you to explicitly shred/overwrite the data with zeros or null characters the exact moment after sending the sensitive data to the Encap SDK. ### How to shred arrays Once the secret has been used, you should immediately clear the array contents. It is best practice to wrap your logic in a `try-finally` block to ensure that the memory is shredded, even if an exception occurs during processing. #### Example of overwriting a CharArray ```kotlin title="Example: Overwriting a CharArray" fun processPin(pin: CharArray) { try { // 1. Process the sensitive data verifyPin(pin) } finally { // 2. Shred the data by overwriting it with zeros pin.fill('\u0000') } } ``` ```java title="Example: Overwriting a CharArray" void processPin(char[] pin) { try { // 1. Process the sensitive data verifyPin(pin); } finally { // 2. Shred the data by overwriting it with zeros Arrays.fill(pin, '\u0000'); } } ``` #### Example of overwriting a ByteArray ```kotlin title="Example: Overwriting a ByteArray" fun processSecret(secret: ByteArray) { try { // 1. Use the sensitive byte array processSecret(secret) } finally { // 2. Shred the data by overwriting it with zeros secret.fill(0) } } ``` ```java title="Example: Overwriting a ByteArray" void processSecret(byte[] secret) { try { // 1. Use the sensitive byte array processSecret(secret); } finally { // 2. Shred the data by overwriting it with zeros Arrays.fill(secret, (byte) 0); } } ``` --- ## Stack trace ## About stack trace The Encap SDK is obfuscated. This means that exceptions generated by the SDK contain obfuscated names instead of actual name classes. This appendix shows you how to retrace a stack trace containing Encap SDK obfuscated names. ## How to retrace a stack trace ### Tools To obtain the original stack trace without any code obfuscation, you can use one or more of the following: :::note Retrace command line tool This tool is bundled into the command line tool package [https://developer.android.com/studio/command-line/retrace](https://developer.android.com/studio/command-line/retrace). It requires: - A path to a mapping file. - A path to a file that contains a stack trace or stack trace from standard input `retrace mappingFile [stackTraceFile]`. ::: :::note ProGuard GUI This tool can be found in the Android SDK directory under `tools/proguard/bin/proguardgui.sh`. Running this shell script will start the ProGuard program. The **ReTrace** tab allows you to input a mapping file and load a stack trace. **Example: Input a mapping file and load a stack trace in ProGuard GUI** Screenshot showing ReTrace in ProGuard GUI ::: ### Mapping file You can find the mapping file for retracing the Encap API in the Nexus repository server directory, alongside the Encap Android API library `.aar` file. The mapping file has a `.map` extension. Each release of the Encap API has its own map file which is needed to retrace a stack trace from the Encap API. ### Retracing a stack trace from an obfuscated build When the application is obfuscated, you can retrace the stack trace from the specific build of the app by supplying the mapping file of the specific build to the `retrace` command. :::tip Where is the mapping file? You can typically find the mapping file at `build/outputs/mapping/release/mapping.txt`. ::: **Example: Use the `retrace` command for an obfuscated app** ``` $ retrace app/build/outputs/mapping/release/mapping.txt Waiting for stack-trace input... com.encapsecurity.encap.android.client.api.exception.AuthenticationFailedException[message=Incorrect response to authentication challenge., isRecoverable=true, errorCode=serverErrorAuthenticationFailed, remainingAttempts=2] at java.lang.reflect.Constructor.newInstance0(Native Method) at java.lang.reflect.Constructor.newInstance(Constructor.java:343) at od.o(:4) at yq0$a.b(Unknown Source:21) at fo0$a.e(Unknown Source:22) at jj0.(Unknown Source:3) at jw0.l(Unknown Source:13) at hw0.run(:1) at java.lang.Thread.run(Thread.java:1012) ^D com.encapsecurity.encap.android.client.api.exception.AuthenticationFailedException[message=Incorrect response to authentication challenge., isRecoverable=true, errorCode=serverErrorAuthenticationFailed, remainingAttempts=2] at java.lang.reflect.Constructor.newInstance0(Native Method) at java.lang.reflect.Constructor.newInstance(Constructor.java:343) at com.encapsecurity.nz.cp(nz.java:0) at com.encapsecurity.bph$cp.b(bph.java:21) at com.encapsecurity.bix$cp.cp(bix.java:22) at com.encapsecurity.aqj.(aqj.java:3) at com.encapsecurity.kc.l(kc.java:13) at com.encapsecurity.kc.cp(kc.java:0) at com.encapsecurity.kc.bps(kc.java:0) at java.lang.Thread.run(Thread.java:1012) ``` ### Retracing the stack trace from an obfuscated API When the API is obfuscated, you can retrace the stack traces containing obfuscated names in `com.encapsecurity.*` by supplying the mapping file of the API. **Example: Use the `retrace` command for an obfuscated API** ``` $ retrace encap-android-api.map Waiting for stack-trace input... com.encapsecurity.encap.android.client.api.exception.AuthenticationFailedException[message=Incorrect response to authentication challenge., isRecoverable=true, errorCode=serverErrorAuthenticationFailed, remainingAttempts=2] at java.lang.reflect.Constructor.newInstance0(Native Method) at java.lang.reflect.Constructor.newInstance(Constructor.java:343) at com.encapsecurity.nz.cp(nz.java:0) at com.encapsecurity.bph$cp.b(bph.java:21) at com.encapsecurity.bix$cp.cp(bix.java:22) at com.encapsecurity.aqj.(aqj.java:3) at com.encapsecurity.kc.l(kc.java:13) at com.encapsecurity.kc.cp(kc.java:0) at com.encapsecurity.kc.bps(kc.java:0) at java.lang.Thread.run(Thread.java:1012) ^D com.encapsecurity.encap.android.client.api.exception.AuthenticationFailedException[message=Incorrect response to authentication challenge., isRecoverable=true, errorCode=serverErrorAuthenticationFailed, remainingAttempts=2] at java.lang.reflect.Constructor.newInstance0(Native Method) at java.lang.reflect.Constructor.newInstance(Constructor.java:343) at com.encapsecurity.encap.android.client.internal.exception.ErrorCodeExceptionFactory.cp(ErrorCodeExceptionFactory.java:0) at com.encapsecurity.encap.android.client.internal.communication.response.Response$JsonResponse.b(Response.java:21) at com.encapsecurity.encap.android.client.internal.communication.response.CancelSessionResponse$CancelSessionJsonResponse.cp(CancelSessionResponse.java:22) at com.encapsecurity.encap.android.client.internal.communication.response.FinishResponse.(FinishResponse.java:3) at com.encapsecurity.encap.android.client.internal.api.impl.AuthenticatorImpl.l(AuthenticatorImpl.java:13) at com.encapsecurity.encap.android.client.internal.api.impl.AuthenticatorImpl.cp(AuthenticatorImpl.java:0) at com.encapsecurity.encap.android.client.internal.api.impl.AuthenticatorImpl.bps(AuthenticatorImpl.java:0) at java.lang.Thread.run(Thread.java:1012) ``` --- ## Thread handling ## About thread handling The Encap API creates a background thread to perform the necessary communication with back-end servers when the application invokes one of the asynchronous methods. These operations happen on a separate thread, therefore they do not block the application's user interface. ## How does thread handling work? Once a back-end operation finishes, the Encap API runs the callback that was passed to the method call in the context of the activity's `runOnUiThread(Runnable)`, so that the callback can update the application's user interface. :::tip Note This process happens regardless of whether the operation is successful or not. ::: --- ## Version errors ## About version errors If your client SDK is too old, too new, or blocklisted (sometimes referred to as blacklisted), then you will get notified during normal operations. ## How do version errors work? If you start an operation such as an authentication: 1. The server will check the version number of the client SDK. 2. The server will report back if the client SDK is too old, too new, or blocklisted. ## Version server errors The table below shows a list of errors that are possible for you to receive. :::CustomTable{columnWidths="50% 50%"} | **Error** | **Description** | | :-- | :-- | | `serverErrorApiVersionTooOldForServer` | The client SDK is too old for the server (two years before the introduction of a new server version). **Example**: The client SDK is version 3.4 and the server version is 3.11. | | `serverErrorApiVersionTooNewForServer` | The client SDK is too new for the server. **Example**: The client SDK is version 3.12 and the server is version 3.11. | | `serverErrorApiVersionTooOldForAppConfig` | The server has its own minimum version configured in the application configuration (`appConfig`) and the client SDK is older than that version. | | `serverErrorApiVersionBlacklisted` | The client SDK version is blocklisted. **Note**: The server can configure one or several client SDK versions to be blocklisted. | ::: ## Version client errors The table below shows a list of errors that are possible for you to receive. :::CustomTable{columnWidths="50% 50%"} | **Error** | **Description** | | :-- | :-- | | `clientErrorRegistrationDataTooOld` | The registration data was created with an outdated version of the Encap protocol. The client SDK version is new enough, but the device has not communicated with the Encap server in a significant amount time (three years before the introduction of the server version). **Note**: This is a rare error. The error code comes from the client itself. | ::: ### How to resolve version client errors If you receive the error `clientErrorRegistrationDataTooOld`, then a re-activation is required. You cannot resolve the issue by upgrading the client alone. This is because the server will not be able to understand the registration data stored on the client. ## Compatibility - We guarantee that a client can communicate with the server for two years. With a compatible client version, you can always register or use a valid registration against the server. - We cannot guarantee that a significantly old registration with no usage can be used on a new client. --- ## Authentication methods Encap supports several different authentication methods. Not every authentication method can be used on every platform. Below you will find: - The supported authentication methods for Android. - How to use these authentication methods. - The names of the parameters that you need in order to activate and authenticate with these methods. :::tip Available authentication methods The number of authentication methods could be limited by: - The application configuration on the Encap server, identified by the `applicationId`. - The mobile device's hardware. - The mobile device's state. ::: ## Device :::CustomTable{columnWidths="33% 33% 33%"} | **Authentication method name** | **ActivationParameter** | **AuthenticationParameter** | | :-- | :-- | :-- | | `AuthMethod.DEVICE` | `DeviceActivationParameter` | `DeviceAuthParameter` | ::: The device is a single-factor authentication method. You have the option to request single-factor device activation and authentication. This is indicated in the Encap client API in the following objects: - `StartActivationResult` - `StartAuthenticationResult` You can access this through the lists returned by the following methods: - `getAuthMethodsForActivation()` - `getAuthMethodsForAuthentication()` The Encap client decides whether to complete the activation or authentication request with single or two factors. - For single-factor activation, it passes `DeviceActivationParameter` to `finishActivation()`. - For single-factor authentication, it passes `DeviceAuthParameter` to `finishAuthentication()`. :::tip Note A single-factor authentication method cannot be used to add a two-factor authentication method. You need to configure on the server which two-factor authentication methods can be used to add other two-factor authentication methods. When you activate a two-factor authentication method, Encap will always activate the device as well. There are only a few use cases where activating only the device makes sense, such as with a pure authenticator app. ::: ## PIN :::CustomTable{columnWidths="33% 33% 33%"} | **Authentication method name** | **ActivationParameter** | **AuthenticationParameter** | | :-- | :-- | :-- | | `AuthMethod.DEVICE_PIN` | `DevicePinActivationParameter` | `DevicePinAuthParameter` | ::: ### Activation :::tip Our recommendation We recommend that you activate the PIN first so that you will always have a backup. This could be useful if: - Other authentication methods get invalidated or temporarily locked. - The user cancels Biometrics, if it is not possible for them to use it at that time. You can add Biometrics at a later point using the `addOrUpdate` operation, as described in the [Add or update](#add-or-update) section for Biometric Prompt. ::: Activating the PIN is similar to activating a device. However, you have to set the PIN on the activation parameter object. The app is responsible for making the UI where the user can set a PIN. The `StartActivationResult` operation can be used to present the UI in the correct way, in terms of: - Password type. - Password length. - Keyboard type. You can get this information using: :::CustomTable{columnWidths="25% 75%"} | **Operation** | **Description** | | :-- | :-- | | `getMinPinCodeLength()` | The minimum length for PIN configured on the server. | | `getMaxPinCodeLength()` | The maximum length for PIN configured on the server. | | `getPinCodeType()` | The type of the input field configured on the server. | ::: ```kotlin title="Example: How to activate a PIN" // Activation code should come from an other source, for example a web page. controller.startActivation(activationCode, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartActivationResult) { // Ready to continue to finishActivate. See result on how to proceed. // PIN should have been typed into the UI of the app, usually between the start and finish call. val activationParameter = DevicePinActivationParameter(pinCode) controller.finishActivation(activationParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishActivationResult) { // The authentication method is activated. } }) } }) ``` ```java title="Example: How to activate a PIN" // Activation code should come from an other source, for example a web page. controller.startActivation(activationCode, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartActivationResult result) { // Ready to continue to finishActivate. See result on how to proceed. // PIN should have been typed into the UI of the app, usually between the start and finish call. DevicePinActivationParameter activationParameter = new DevicePinActivationParameter(pinCode); controller.finishActivation(activationParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishActivationResult result) { // The authentication method is activated. } }); } }); ``` :::warning Do not store the end-user's PIN You should not store the end-user's PIN anywhere. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-android/appendix/security-best-practices) appendix. ::: ### Authentication Authenticating with a PIN is similar to activating a PIN. However, you use the `startAuthentication` and `finishAuthetication` operations instead. The results of `StartAuthenticationResult` gives you the same information as in activation (`StartActivationResult`), so that you can set up the UI for PIN input. ```kotlin title="Example: How to authenticate with a PIN" controller.startAuthentication(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAuthenticationResult) { // Ready to continue to finishAuthentication. See result on how to proceed. // PIN should have been typed into the UI of the app, usually between the start and finish call. val authParameter = DevicePinAuthParameter(pinCode) controller.finishAuthentication(authParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // The authentication method is activated. } }) } }) ``` ```java title="Example: How to authenticate with a PIN" controller.startAuthentication(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAuthenticationResult result) { // Ready to continue to finishAuthentication. See result on how to proceed. // PIN should have been typed into the UI of the app, usually between the start and finish call. DevicePinAuthParameter authParameter = new DevicePinAuthParameter(pinCode); controller.finishAuthentication(authParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // The authentication method is activated. } }); } }); ``` ### Add or update (change PIN) You can use the `addOrUpdate` operation to update the PIN. This looks similar to authenticating with a PIN, however, you have to set the old PIN on the `AuthParameter`, and the new PIN on the `ActivationParameter`. ```kotlin title="Example: How to update a PIN" controller.startAddOrUpdate(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAddOrUpdateResult) { // Old and new PIN needs to come from the apps UI, usually between the start and finish call. val authParameter = DevicePinAuthParameter(oldPin) val activateParameter = DevicePinActivationParameter(newPin) controller.finishAddOrUpdate(authParameter, activateParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // Successfully changed the PIN. } }) } }) ``` ```java title="Example: How to update a PIN" controller.startAddOrUpdate(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAddOrUpdateResult result) { // Old and new PIN needs to come from the apps UI, usually between the start and finish call. AuthParameter authParameter = new DevicePinAuthParameter(oldPin); ActivationParameter activateParameter = new DevicePinActivationParameter(newPin); controller.finishAddOrUpdate(authParameter, activateParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // Successfully changed the PIN. } }); } }); ``` ## BiometricPrompt :::CustomTable | **Authentication method name** | **ActivationParameter** | **AuthenticationParameter** | | :-- | :-- | :-- | | `AuthMethod.DEVICE_ANDROID_BIOMETRIC_PROMPT` | `DeviceAndroidBiometricPromptActivationParameter` | `DeviceAndroidBiometricPromptAuthParameter` | ::: ### Overview Biometric Prompt was introduced in Android 9. The Encap Android API 3.13 and higher supports the AndroidX Biometric support library, which is a recommended support library from Google that offers backward compatibility for Biometric Prompt. This can simplify the implementation for an app, as you can implement Biometric Prompt for all devices instead of implementing Fingerprint from Android 6-8, and then Biometric Prompt for Android 9 and higher. When the AndroidX Biometric library dependency is added to the app, the SDK will pick this up and switch the implementation; making BiometricPrompt available for Android 6 and later. If the dependency is not added, then you can only use Biometric Prompt for Android 9 and later. ### How to implement 1. You must enable `DEVICE_ANDROID_BIOMETRIC_PROMPT` and an authentication method in the application configuration. 2. Add the following entries to `AndroidManifest` of the app: ```xml ``` 3. **Optional**: If you want to get Biometric Prompt for older devices as well, then you must add the following dependency to the Gradle build file: ```kotlin implementation("androidx.biometric:biometric:1.1.0") ``` ```groovy implementation "androidx.biometric:biometric:1.1.0" ``` :::tip Using the correct constructor The `DeviceAndroidBiometricPromptActivationParameter` and `DeviceAndroidBiometricPromptAuthParameter` classes have the following constructors: - Two constructors with a `Fragment` or `FragmentActivity` parameter. You can use these with the AndroidX Biometric Prompt library. - Other constructors without a `Fragment` or `FragmentActivity` parameter. You can use these with the native Android BiometricPrompt. If you use the wrong constructor, you will get an exception. ::: ### Activation Although we recommend that you activate a PIN first so that you have a fallback, it is possible to activate Biometrics directly. Before you can set this up: - Biometrics need to be added as an authentication method in the application configuration on the Encap server, identified by the `applicationId`. - Biometrics need to be enabled on the mobile device. To verify whether you can activate Biometrics, you can check `StartActivationResult.getAuthMethodForActivation` to see if the list contains `AuthMethod.DEVICE_ANDROID_BIOMETRIC_PROMPT`. If it does, then you are ready to finish the activation. The activation parameters for Biometric Prompt differ from device and PIN, and require more data to be filled out. You can control the following: - Title **(required)** - Subtitle - Description - Name of the negative button on the dialogue **(required)** The constructor of the `ActivationParameter` differs depending on if you are using the AndroidX Biometric prompt library or not: - If you are using the library, then you should use the constructor with `Fragment` or `FragmentActivity`. - If you are not using the library, then use the constructor without `Fragment` or `FragmentActivity`. ```kotlin title="Example: How to activate Biometric Prompt" // Activation code should come from another source, for example a web page. controller.startActivation(activationCode, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartActivationResult) { // Ready to continue to finishActivate. See result on how to proceed. val activationParameter = DeviceAndroidBiometricPromptActivationParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel") controller.finishActivation(activationParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishActivationResult) { // The authentication method is activated. } }) } }) ``` ```java title="Example: How to activate Biometric Prompt" // Activation code should come from another source, for example a web page. controller.startActivation(activationCode, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartActivationResult result) { // Ready to continue to finishActivate. See result on how to proceed. DeviceAndroidBiometricPromptActivationParameter activationParameter = new DeviceAndroidBiometricPromptActivationParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel"); controller.finishActivation(activationParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishActivationResult result) { // The authentication method is activated. } }); } }); ``` :::tip Note Activating Biometrics requires the user to authenticate. This differs from iOS where it is not needed during activation. It is technically possible to turn the dialogue off on the Android platform, but we do not expose that possibility in our Encap library. This would lower the security, as the key would not be bound to the Biometrics. ::: ### Authentication Authenticating with Biometrics is similar to activating with Biometrics. However, you use the `startAutentication` and `finishAuthentication` instead, with `DeviceAndroidBiometricPromptAuthParameter` as the `AuthParameter`. First, you need to make sure that Biometrics is a possible authentication method. This means that it is: - Configured on the server. - Activated and enabled on the phone. - In a state where it can be used. To verify this, you can check `StartAuthenticationResult.getAuthMethodForAuthentication()` to see if the list contains `AuthMethod.DEVICE_ANDROID_BIOMETRIC_PROMPT`. Just as with activation for Biometric Prompt, you need to fill out some additional information for the authentication parameters (`AuthParameter`). You can control the following: - Title **(required)** - Subtitle - Description - Name of the negative button on the dialogue **(required)** ```kotlin title="Example: How to authenticate with biometrics" controller.startAuthentication(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAuthenticationResult) { // Ready to continue to finishAuthentication. See result on how to proceed. val authParameter = DeviceAndroidBiometricPromptAuthParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel") controller.finishAuthentication(authParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // The authentication method is activated. } }) } }) ``` ```java title="Example: How to authenticate with biometrics" controller.startAuthentication(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAuthenticationResult result) { // Ready to continue to finishAuthentication. See result on how to proceed. DeviceAndroidBiometricPromptAuthParameter authParameter = new DeviceAndroidBiometricPromptAuthParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel"); controller.finishAuthentication(authParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // The authentication method is activated. } }); } }); ``` ### Add or update A typical use case is to: 1. Activate a PIN as a fallback, as described in the [Activation](#activation) section for PIN. 2. Use the `addOrUpdate` operation to add Biometrics. If you want to add a new authentication method, then you need to have a two-factor authentication method already registered. You can add Biometrics from any two-factor authentication method, as long as it is configured in the application configuration on the Encap server, identified by the `applicationId`. PIN is the most commonly used authentication method for adding Biometrics. You can verify whether you have a two-factor authentication method that can add Biometrics by checking the `getAuthMethodForAuthentication()` function on the returned `StartAddOrUpdateResult` object. ```kotlin title="Example: How to add biometrics from PIN" controller.startAddOrUpdate(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAddOrUpdateResult) { // Old and new PIN needs to come from the apps UI, usually between the start and finish call. // PIN should have been typed into the UI of the app, usually between the start and finish call. val authParameter = DevicePinAuthParameter(pinCode) val activationParameter = DeviceAndroidBiometricPromptActivationParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel") controller.finishAddOrUpdate(authParameter, activationParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // Successfully added Biometrics using PIN. } }) } }) ``` ```java title="Example: How to add biometrics from PIN" controller.startAddOrUpdate(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAddOrUpdateResult result) { // Old and new PIN needs to come from the apps UI, usually between the start and finish call. // PIN should have been typed into the UI of the app, usually between the start and finish call. DevicePinAuthParameter authParameter = new DevicePinAuthParameter(pinCode); DeviceAndroidBiometricPromptActivationParameter activationParameter = new DeviceAndroidBiometricPromptActivationParameter(context, fragment) .setTitle("MyTitle") .setSubtitle("MySubtitle") .setDescription("MyDescription") .setNegativeButtonText("Cancel"); controller.finishAddOrUpdate(authParameter, activationParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // Successfully added Biometrics using PIN. } }); } }); ``` ### Error handling The error handling for Biometric Prompt is similar to regular authentication, however, you have to consider actions for the error codes of failed Biometric authentications in addition. The `isRecoverableError()` operation can be used to find out whether `finishAuthentication()` can be called again. :::danger Risk of data invalidation If any of the following occur, then the Encap authentication data is invalidated and a re-activation is required: - Biometrics are added to the device. - All Biometrics are removed from the device. - The secure lock screen is disabled. See error code `clientErrorAuthDataInvalidated` for more details. ::: ### Fall back to PIN A fall back to PIN could provide a better user experience for your end-user in some use cases, instead of just failing the authentication. For example: - If the end-user cancels Biometric Prompt. - If the end-user uses the incorrect finger too many times. #### How to implement 1. First, a PIN needs to be activated. You can verify whether PIN is an option to fall back to by looking for `DEVICE_PIN`: ```kotlin title="Example: Look for DEVICE_PIN" startAuthenticationResult.authMethodsForAuthentication.contains(DEVICE_PIN) ``` ```java title="Example: Look for DEVICE_PIN" startAuthenticationResult.getAuthMethodsForAuthentication().contains(DEVICE_PIN); ``` 2. Next, you need to look for the correct error codes in the `OnFailure` scenario in `finishAuthenticaion`: - If you only want to fall back to PIN if Biometrics have been locked, then you need to check if the error code corresponds to either: - `clientErrorAndroidBiometricPromptErrorLockout` - `clientErrorAndroidBiometricPromptLockoutPermanent` - If you also want to fall back to PIN if the end-user cancels the Biometric Prompt, then you also need to look for: - `clientErrorAndroidBiometricPromptErrorCanceled` - `clientErrorAndroidBiometricPromptErrorUserCanceled` ```kotlin title="Example: Look for correct error codes" // In OnFailure if (canFallbackToPin() && (isLockedError(errorCode) || isCanceledError(errorCode))) { // Go to the PIN flow. // Calling startAuthentication is not needed, as we are in a retryable state. } ``` ```java title="Example: Look for correct error codes" // In OnFailure if (canFallbackToPin() && (isLockedError(errorCode) || isCanceledError(errorCode))) { // Go to the PIN flow. // Calling startAuthentication is not needed, as we are in a retryable state. } ``` :::tip Note If the end-user uses the wrong finger too many times, then Biometrics will be locked or permanently locked. This is only a local state, and is resolved on the phone itself. Most phones will unlock Biometrics after turning off the screen, then using a PIN or Pattern to unlock it again. ::: ### Confirmation Required On some mobile devices, it is possible to control whether you want a button to confirm that you are authenticating with your face or not. This confirmation button is designed to prevent accidental authentication by just looking at the screen when the Biometric Prompt appears. The activation and authentication parameter classes for BiometricPrompt are as follows: - `DeviceAndroidBiometricPromptActivationParameter` - `DeviceAndroidBiometricPromptAuthParameter` In these classes, you can set a hint to override this setting on the mobile device. To do this, you have to set `setConfirmationRequired()` to either `true` or `false`. The default value is `true`. It is not recommended to set to `false` for high-value transactions. :::tip Note This is just a hint to the system. The system could still ignore the hint and: - Show the confirmation button even though the hint is set to `false`. - Show no button even if the hint is set to `true`. An alternative to this Android feature is to implement the confirmation button in your UI yourself before calling `finishAuthentication()` or `finishActivation()`. ::: ### Multiple controller scenario If you are activating multiple registrations, but only want the end-user to confirm with Biometrics once (to activate Biometrics for all of the registrations), then you can use `setSingleBiometricPromptEnabled()`. To do this: 1. For the first `DeviceAndroidBiometricPromptActivationParameter` object, set this to `false`. 2. For the second and following controllers, set it to `true`. This will allow `finishActivation()` to complete the activation without interaction from the end-user for the following controllers. :::tip Note This has to be done within a 60 seconds time period for it to work. ::: --- ## Account recovery(Configure-features) :::info About this documentation This documentation only describes how to configure the SDK for our account recovery feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/account-recovery)   [**Encap**](/docs/mobile-identity/encap/features/account-recovery) ::: ## How does account recovery work? ### Recovery methods For Android, recovery is currently supported with the following recovery methods: | **Name** | **Recovery method** | | :-- | :-- | | Recovery code | `CLOUD_BACKUP_RECOVERY_CODE` | | Face scan | `CLOUD_BACKUP_SERVER_SIDE_FACE` | #### Recovery code :::warning Do not store the end-user's recovery code You should not store the end-user's recovery code anywhere. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-android/appendix/security-best-practices) appendix. ::: A recovery code is code that is chosen and remembered by the end-user. - Backup-based recovery uses a secret code (`recoveryCode`). - It is associated with the recovery method `CLOUD_BACKUP_RECOVERY_CODE`. - This type of recovery is deleted after the recovery is performed. ```kotlin title="Example: Recovery method with recovery code" RecoveryCodeRecoveryParameter(recoveryCode) ``` ```java title="Example: Recovery method with recovery code" new RecoveryCodeRecoveryParameter(recoveryCode); ``` :::note Note The parameter `RecoveryCodeRecoveryParameter` replaces the former parameter `EncapRecoveryCodeParameter(CLOUD_BACKUP)`, providing an easier constructor. ::: #### Face scan Face scan data is obtained from a face scan of the end-user. This data contains the face scan and optionally, audit trail images. - Recovery with face scan uses face scan data (`faceScanData`). - It is associated with the recovery method `CLOUD_BACKUP_SERVER_SIDE_FACE`. - This type of recovery is kept after the recovery is performed, to avoid the need for another face scan. ```kotlin title="Example: Recovery method with face scan" ServerSideFaceRecoveryParameter(faceScanData) ``` ```java title="Example: Recovery method with face scan" new ServerSideFaceRecoveryParameter(faceScanData); ``` :::warning Important The parameter `ServerSideFaceRecoveryParameter` requires that the end-user has set up face scan for the registration, before adding recovery. To do this, you must use `addOrUpdate(AuthenticationParameter, DeviceServerSideFaceActivationParameter)`. ::: ### Supported backup types Recovery for Android is fully compliant with the [Android Auto Backup](https://developer.android.com/guide/topics/data/backup) feature. ### Prerequisites Account recovery generates secrets that are tied to a specific device. The secrets are stored inside the app files, which the end-user needs to back up. To enable this, you need to ensure that: 1. Your application declares `allowBackup` in its manifest files. ```java title="Example: Enable backup in manifest files" android:allowBackup="true" ``` 2. The file `2c5f882341aa8372a6166769bd469903.xml` is not excluded from the backup in the application manifest section. :::note Note You can skip this step if the manifest does not include the attributes `fullBackupContent` or `dataExtractionRules`. For more information, see [Back up and restore attributes](/docs/mobile-identity/encap/sdk-android/appendix/back-up-restore-attributes.mdx) in our Encap SDK developer documentation. ::: 3. The end-user enables backup in their mobile device's settings. To do this, they can either: - Set up a Google account and enable auto backup to Google Drive. - Set up a cloud backup specific to the their mobile device's manufacturer, such as Samsung Cloud. - Transfer data from another mobile device. - Perform a manual backup to the external storage. :::note Using Google backup Google's auto backup is the most convenient way of backing up and restoring data. However, it runs on its own and in some cases files can be backed up with a delay reaching up to 24 hours. This makes recovery on another device impossible until that time. ::: ### Token authorisation When you are using our SDKs for account recovery, you need to provide a token to authorise the operation. - Authorisation tokens are issued by our server when performing certain SDK operations. - In these operations, you need to set what purpose you will use the token for. - The token is returned back to the app as a response. - This token is used to authorise the next account recovery operation after a successful activation or authentication. :::info What does this mean? For example, this makes it possible to implement a flow that both registers the end-user and sets up recovery for the registration, without an additional authentication. ::: #### Operations that require a token An authorisation token is required for the following recovery-related operations: - `addOrUpdateRecovery` - `deleteRecovery` #### Operations that can yield a token The server will issue an authorisation token for the following operations: - `finishActivation` - `finishAuthentication` - `finishAddOrUpdateRecovery` - `finishRecovery` - `finishDeleteRecovery` #### Token purpose To request the authorisation token, you must provide one of the following purposes in the finish call: - `TokenPurpose.ADD_OR_UPDATE_RECOVERY` - `TokenPurpose.DELETE_RECOVERY` :::note Note The default value is `TokenPurpose.UNSET_PURPOSE`. ::: ## Configure the SDK ### How to get a token The operations `addOrUpdateRecovery` and `deleteRecovery` require an `EncapToken`. 1. To request a token, you must set the token purpose together with the activation or authentication parameter, using the `setTokenPurpose` method. - If adding or updating recovery, you should use `TokenPurpose.ADD_OR_UPDATE_RECOVERY`. - If deleting recovery, you should use `TokenPurpose.DELETE_RECOVERY`. ```kotlin title="Example: How to request a token during activation" val activationParameter = DevicePinActivationParameter(userPinCode).apply { tokenPurpose = TokenPurpose.ADD_OR_UPDATE_RECOVERY } ``` ```java title="Example: How to request a token during activation" ActivationParameter activationParameter = new DevicePinActivationParameter(userPinCode); activationParameter.setTokenPurpose(TokenPurpose.ADD_OR_UPDATE_RECOVERY); ``` 2. The token is returned with the usual operation response. To learn how to access it, see example below: ```kotlin title="Example: How to access a token" override fun onSuccess(result: FinishActivationResult) { val token = result.encapToken } ``` ```java title="Example: How to access a token" public void onSuccess(FinishActivationResult result) { EncapToken token = result.getEncapToken(); } ``` ### Recovery Code The following describes how to add, perform and delete recovery using a recovery code. #### Add account recovery To add account recovery and connect it to the end-user's registration, you can perform the `addOrUpdateRecovery` operation. 1. Call `startAddOrUpdateRecovery` and pass in the `EncapToken` you acquired from the previous step. 2. If this is successful, then you can call `finishAddOrUpdateRecovery` with an `RecoveryCodeRecoveryParameter`. :::note Note - The `RecoveryCodeRecoveryParameter` takes a `recoveryCode` that the end-user creates. - The end-user needs to use this code when they perform a recovery later on. ::: ```kotlin title="Example: Add account recovery, with recovery code" controller.startAddOrUpdateRecovery( encapToken = , appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartAddOrUpdateRecoveryResult) { ... } } ) controller.finishAddOrUpdateRecovery( recoveryParameter = RecoveryCodeRecoveryParameter(), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishAddOrUpdateRecoveryResult) { ... } } ) ``` ```java title="Example: Add account recovery, with recovery code" controller.startAddOrUpdateRecovery( , new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartAddOrUpdateRecoveryResult result) { ... } } ); controller.finishAddOrUpdateRecovery( new RecoveryCodeRecoveryParameter(), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishAddOrUpdateRecoveryResult result) { ... } } ); ``` #### Perform an account recovery To recover an end-user's registration, you can perform the `startRecovery` and `finishRecovery` operations. This works similarly in concept to the activation process, where you must select and enable a new authentication method. - You can only enable one authentication method for a single recovery. - To add more authentication methods, you can perform the `addOrUpdate` operation. ```kotlin title="Example: How to perform an account recovery with recovery code, activating PIN" controller.startRecovery( object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartRecoveryResult) { ... } } ) controller.finishRecovery( recoveryParameter = RecoveryCodeRecoveryParameter(), activationParameter = DevicePinActivationParameter(), appCallback = object : AsyncStateChangedCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishRecoveryResult) { ... } override fun onStateChanged(state: EncapController.State) { ... } } ) ``` ```java title="Example: How to perform an account recovery with recovery code, activating PIN" controller.startRecovery( new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartRecoveryResult result) { ... } } ); controller.finishRecovery( new RecoveryCodeRecoveryParameter(), new DevicePinActivationParameter(), new AsyncStateChangedCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishRecoveryResult result) { ... } public void onStateChanged(EncapController.State state) { ... } } ); ``` :::note What is the recovery code? The `` is a secret code that is provided by the end-user, and is only known by them. - The end-user chooses the recovery code, which is a parameter to the `finishAddOrUpdateRecovery()` operation. - The end-user must then provide the same recovery code as a parameter to the `finishRecovery()` operation. - The end-user's choice of authentication method to activate is also a parameter to the `finishRecovery()` operation. ::: #### Delete a recovery To remove an active recovery, you can perform the `startDeleteRecovery` and `finishDeleteRecovery` operations. The `` has to be requested with an authentication, and must have the token purpose set to `DELETE_RECOVERY`. ```kotlin title="Example: How to delete a recovery, of type recovery code" controller.startDeleteRecovery( encapToken = , appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartDeleteRecoveryResult) { ... } } ) controller.finishDeleteRecovery( recoveryParameter = RecoveryCodeRecoveryParameter(), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishDeleteRecoveryResult) { ... } } ) ``` ```java title="Example: How to delete a recovery, of type recovery code" controller.startDeleteRecovery( , new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartDeleteRecoveryResult result) { ... } } ); controller.finishDeleteRecovery( new RecoveryCodeRecoveryParameter(), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishDeleteRecoveryResult result) { ... } } ); ``` ### Face scan The following describes how to add, perform and delete recovery using face scan. #### Add account recovery To add account recovery and connect it to the end-user's registration, you can perform the `addOrUpdateRecovery` operation. 1. If the registration does not have server-side face, then you add it. To do this: 1. Call `startAddOrUpdate` with `StartAddOrUpdateParameter(authMethod = DEVICE_SERVER_SIDE_FACE)`. 2. Call `finishAddOrUpdate` with a valid `AuthenticationParameter` (typically for PIN or biometrics), and a `DeviceServerSideFaceActivationParameter` containing the face scan data of the end-user. 3. Request a token with `TokenPurpose.ADD_OR_UPDATE_RECOVERY`. 2. Call `startAddOrUpdateRecovery` and pass in the `EncapToken` that you acquired from the previous step. 3. If this is successful, then you can call `finishAddOrUpdateRecovery` with an empty `ServerSideFaceRecoveryParameter`. :::note Note - The `DeviceServerSideFaceActivationParameter` takes a `faceScanData` containing the face scan data of the end-user. - No face scan data is needed when adding recovery using the `ServerSideFaceRecoveryParameter`, as the existing face scan from `addOrUpdate` is used. - The end-user needs to perform a new face scan when they perform a recovery later on. ::: ```kotlin title="Example: Add account recovery, with face scan" controller.startAddOrUpdate( startParameter = StartAddOrUpdateParameter(authMethod = DEVICE_SERVER_SIDE_FACE), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartAddOrUpdateResult) { ... } } ) controller.finishAddOrUpdate( authParameter = DevicePinAuthParameter(), activationParameter = DeviceServerSideFaceActivationParameter(FaceScanData()), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishAuthenticationResult) { ... } } ) controller.startAddOrUpdateRecovery( encapToken = , appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartAddOrUpdateRecoveryResult) { ... } } ) controller.finishAddOrUpdateRecovery( recoveryParameter = ServerSideFaceRecoveryParameter(), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishAddOrUpdateRecoveryResult) { ... } } ) ``` ```java title="Example: Add account recovery, with face scan" controller.startAddOrUpdate( new StartAddOrUpdateParameter(DEVICE_SERVER_SIDE_FACE), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartAddOrUpdateResult result) { ... } } ); controller.finishAddOrUpdate( new DevicePinAuthParameter(), new DeviceServerSideFaceActivationParameter(new FaceScanData()), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishAuthenticationResult result) { ... } } ); controller.startAddOrUpdateRecovery( , new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartAddOrUpdateRecoveryResult result) { ... } } ); controller.finishAddOrUpdateRecovery( new ServerSideFaceRecoveryParameter(), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishAddOrUpdateRecoveryResult result) { ... } } ); ``` #### Perform an account recovery To recover an end-user's registration, you can perform the `startRecovery` and `finishRecovery` operations. This works similarly in concept to the activation process, where you must select and enable a new authentication method. - You can only enable one authentication method for a single recovery. - To add more authentication methods, you can perform the `addOrUpdate` operation. ```kotlin title="Example: How to perform an account recovery with face scan, activating PIN" controller.startRecovery( appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartRecoveryResult) { ... } } ) controller.finishRecovery( recoveryParameter = ServerSideFaceRecoveryParameter(FaceScanData()), activationParameter = DevicePinActivationParameter(), appCallback = object : AsyncStateChangedCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishRecoveryResult) { ... } override fun onStateChanged(state: EncapController.State) { ... } } ) ``` ```java title="Example: How to perform an account recovery with face scan, activating PIN" controller.startRecovery( new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartRecoveryResult result) { ... } } ); controller.finishRecovery( new ServerSideFaceRecoveryParameter(new FaceScanData()), new DevicePinActivationParameter(), new AsyncStateChangedCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishRecoveryResult result) { ... } public void onStateChanged(EncapController.State state) { ... } } ); ``` :::note What is the face scan data? - The `` contains a face scan of the end-user, optionally with audit trail images. - The end-user's choice of authentication method to activate is a parameter to the `finishRecovery()` operation. ::: #### Delete a recovery To remove an active recovery, you can perform the `startDeleteRecovery` and `finishDeleteRecovery` operations. The `` has to be requested with an authentication, and must have the token purpose set to `DELETE_RECOVERY`. ```kotlin title="Example: How to delete a recovery, of type face scan" controller.startDeleteRecovery( encapToken = , appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: StartDeleteRecoveryResult) { ... } } ) controller.finishDeleteRecovery( recoveryParameter = ServerSideFaceRecoveryParameter(), appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: FinishDeleteRecoveryResult) { ... } } ) ``` ```java title="Example: How to delete a recovery, of type face scan" controller.startDeleteRecovery( , new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(StartDeleteRecoveryResult result) { ... } } ); controller.finishDeleteRecovery( new ServerSideFaceRecoveryParameter(), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(FinishDeleteRecoveryResult result) { ... } } ); ``` ## Additional operations These additional operations can help you to create app logic in scenarios where a backup or restore has occurred, so that you can show recovery instead of a normal registration. ### Check if account recovery is added To check whether account recovery is added on a device, you can use the following method: ```kotlin title="Example: Check if recovery is activated" controller.isRecoveryActivated( appCallback = object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { ... } override fun onSuccess(result: Boolean) { ... } } ) ``` ```java title="Example: Check if recovery is activated" controller.isRecoveryActivated( new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { ... } public void onSuccess(Boolean result) { ... } } ) ``` :::note Note In order for the method to detect account recovery, backup has to be restored on the new device first. ::: ### Check if device has been restored from backup To check whether the end-user's device has been restored from backup and your app is ready to perform account recovery, you can use the following app flow: 1. Check that the boolean result of `isActivated(AsyncCallback)` is `false`. 2. Check that the boolean result of `isRecoveryActivated(AsyncCallback)` is `true` before performing an account recovery. ```kotlin title="Example: Check if restoration from backup has occurred" val isActivated = // the Boolean result of the controller.isActivated(AsyncCallback) val isRecoveryActivated = // the Boolean result of the controller.isRecoveryActivated(AsyncCallback) if (!isActivated && isRecoveryActivated) { // recovery has been activated and can be used to recover registration } ``` ```java title="Example: Check if restoration from backup has occurred" Boolean isActivated = // the Boolean result of the controller.isActivated(AsyncCallback) Boolean isRecoveryActivated = // the Boolean result of the controller.isRecoveryActivated(AsyncCallback) if (!isActivated && isRecoveryActivated) { // recovery has been activated and can be used to recover registration } ``` --- ## App attestation(Configure-features) :::info About this documentation This documentation only describes how to configure the SDK for our app attestation feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/app-attestation)   [**Encap**](/docs/mobile-identity/encap/features/app-attestation) ::: ## Supported operations Attestation can be performed during activation, recovery, or any kind of authentication. ## How to configure app attestation To use our attestation feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK To use Play Integrity, you need to add the required dependency to you app: ```kotlin title="Example: Add dependency to your app" dependencies { implementation("com.google.android.play:integrity:1.1.0") } ``` ```groovy title="Example: Add dependency to your app" dependencies { implementation "com.google.android.play:integrity:1.1.0" } ``` ### Configure the application configuration The process for configuring the application configuration varies depending on whether you are a MobileID customer or an Encap SCA customer. You can use the buttons below to learn how to configure the application configuration for the different products. * [**Configure MobileID**](/docs/mobile-identity/mobileid/features/app-attestation#configure-the-application-configuration): Learn how to configure the application configuration for app attestation * [**Configure Encap SCA**](/docs/mobile-identity/encap/features/app-attestation#configure-the-application-configuration): Learn how to configure the application configuration for app attestation ## Error codes The table below illustrates errors related to the Play Integrity. You can find the corresponding error descriptions in our [SDK error codes](/docs/mobile-identity/encap/sdk-error-codes.mdx#server-errors) documentation. :::CustomTable{columnWidths="25% 75%"} | **Error code** | **Error name** | | :-- | :-- | | 286 | `serverErrorPlayIntegrityTimeout` | | 287 | `serverErrorPlayIntegrityApiFailure` | | 288 | `serverErrorPlayIntegrityPlayServicesOutOfDate` | ::: --- ## Certificate pinning Certificate pinning is a security mechanism that associates a host with its certificate or public key. This ensures that your app only trusts specific certificates or public keys. :::note Are you a MobileID customer? This feature is specific for Encap SCA customers. If you are a MobileID customer, then please see the MobileID [Certificate pinning](/docs/mobile-identity/mobileid/features/certificate-pinning/) feature documentation. ::: ## Calculate the certificate pin To calculate the certificate pin, you need to have the certificate. If you do not have the certificate, then you can get it by doing the following: 1. Go to the URL in your web browser. 2. Use your browser to download the certificate. 3. Calculate the hash with OpenSSL using the appropriate method, depending on the format of the certificate: - **PEM format**: Calculate the hash with OpenSSL as follows: ```shell title="Example: Calculate the hash with OpenSSL" openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64 ``` - **DER format**: Calculate the hash with OpenSSL as follows: ```shell title="Example: Calculate the hash with OpenSSL" openssl x509 -in certificate.der -pubkey -noout -inform der | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64 ``` ## How to set it up You can support TLS/SSL certificate pinning with Encap by calling `setPublicKeyHashes()` on the config object, before setting the config on the controller. - You can add one or more certificate hashes from the web server's certificate chain before establishing a TLS/SSL connection. - Ensure that you add the algorithm used in front of the hash, separated by a `/`. ```kotlin title="Example: Set up certificate pinning with Encap" controller.config = EncapConfig( // Configure required properties... publicKeyHashes = arrayOf("sha256/47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=") ) ``` ```java title="Example: Set up certificate pinning with Encap" EncapConfig.Builder config = new EncapConfig.Builder(); // Configure required properties... config.setPublicKeyHashes(new String[]{"sha256/47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="}); controller.setConfig(config.build()); ``` --- ## Client debug data Client debug data is not intended to be enabled at all times. It can help in error or support situations where extra data is required from the client, in order to understand the state of the application during operations. By default, this feature is disabled. To enable the feature, you have to enable it in the application configuration. See `CLIENT_DEBUG_DATA_ENABLED_OS_TYPES` in our application configuration documentation for more details. Regardless of whether sending debug data is enabled on the server, the end-user can always turn off sending debug data in the `EncapConfig` in the app. They can do this by setting `allowDebugData` to `false`. This is set to `true` by default. In order for data to be sent, the feature has to be enabled both in the application configuration, and in the app's `EncapConfig`. For complete list of the data that is collected by this feature, see the [Client debug data](/docs/mobile-identity/encap/sdk-android/publish-your-app/collected-data.mdx#client-debug-data) section in our **Collected data** section. --- ## Device groups(Configure-features) :::info About this documentation This documentation only describes how to configure the SDK for our device groups feature. To learn about the feature and the full set of implementation requirements, see the main [Device groups](/docs/mobile-identity/encap/features/device-groups) feature documentation. ::: ## How to implement device groups You do not need to configure any specific mobile SDK settings to use device groups. However, to experience the full benefit of dynamic activation, then the devices need to be upgraded to SDK version 3.22 or later. ### Dynamic activation on new devices When a new device running SDK version 3.22 or later is added to a device group which has activated face authentication, then the `DEVICE_SERVER_SIDE_FACE` authentication method is dynamically activated on that device. This allows immediate use of face authentication without requiring the end-user to reactivate it. ### How does dynamic activation work? The SDK automatically handles dynamic activation during standard operational flows, specifically during: - `authentication` - `addOrUpdateAuthMethod` - `addOrUpdateRecovery` During these operations, if the server indicates that the `DEVICE_SERVER_SIDE_FACE` authentication method is available for the device group, then the SDK automatically activates it locally. :::note Synchronised deactivation If an end-user deactivates the face authentication method on one device, it is deactivated and deleted for the entire device group. ::: --- ## Face authentication(Configure-features) :::info About this documentation This documentation only describes how to configure the SDK for our face authentication feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/face-authentication)   [**Encap**](/docs/mobile-identity/encap/features/face-authentication) ::: ## Configure the SDK To use face authentication, you need to: 1. Configure the local build environment. To do this, add the following dependencies to the Gradle build file: ```kotlin title="Example: Add dependencies to Gradle build file" /** * FaceTec dependencies needed for auth method DEVICE_SERVER_SIDE_FACE */ implementation("com.facetec.android:facetec-sdk:9.6.73@aar") implementation("androidx.appcompat:appcompat:1.6.1") ``` ```groovy title="Example: Add dependencies to Gradle build file" /** * FaceTec dependencies needed for auth method DEVICE_SERVER_SIDE_FACE */ implementation "com.facetec.android:facetec-sdk:9.6.73@aar" implementation "androidx.appcompat:appcompat:1.6.1" ``` 2. It is possible to preload FaceTec SDK at the start of the Android Activity. To do this: ```kotlin title="Example: Preload the FaceTec SDK" override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Optional - Preload resources related to the FaceTec SDK so that it can be run as soon as possible. // Run this as soon as you think you might use the SDK for optimal start up performance. FaceTecSDK.preload(this) } ``` ```java title="Example: Preload the FaceTec SDK" @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // Optional - Preload resources related to the FaceTec SDK so that it can be run as soon as possible. // Run this as soon as you think you might use the SDK for optimal start up performance. FaceTecSDK.preload(this); } ``` ## How to implement face authentication :::warning Do not store the end-user's face scan data You should not store the end-user's face scan data anywhere. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-android/appendix/security-best-practices) appendix. ::: ### Overview To implement face authentication, you must typically use the following flow: 1. Invoke the controller start call. 2. Initialise the FaceScan library with the `serverSideFaceInit` parameters from the start result. 3. Invoke the FaceScan activity with `serverSideFaceInit.sessionToken` from the start result. 4. Invoke the controller finish call with the result from the FaceScan . For further details specific to the operation, see the relevant sub-chapters. ### Activation Activation will be supported in a future release. This means that currently, you must: 1. **Activate** with PIN and/or biometrics. 2. Use the **Add or update** operation to add face authentication. ### AddOrUpdate #### Start call For an example of `startAddOrUpdate`, click to expand the collapsible section: :::details Click to expand ```kotlin private lateinit var context: Context private lateinit var controller: Controller private var startAddOrUpdateResult: StartAddOrUpdateResult? = null fun startAddOrUpdate() { // // 1. Invoke the controller start call // controller.startAddOrUpdate(StartAddOrUpdateParameter(DEVICE_SERVER_SIDE_FACE), object : AsyncCallback { override fun onSuccess(result: StartAddOrUpdateResult) { startAddOrUpdateResult = result if (result.authMethodsForActivation.contains(DEVICE_SERVER_SIDE_FACE) || result.authMethodsForAuthentication.contains(DEVICE_SERVER_SIDE_FACE)) { // // 2. Initialise the FaceScan library // val productionKeyText = result.serverSideFaceInit!!.productionKeyText val deviceKeyIdentifier = result.serverSideFaceInit!!.deviceKeyIdentifier val faceScanEncryptionKey = result.serverSideFaceInit!!.encryptionKey FaceTecSDK.initializeInProductionMode(context, productionKeyText, deviceKeyIdentifier, faceScanEncryptionKey) { initializationSuccess -> if (initializationSuccess) { // TODO - Display message to user: Start FaceScan? } else { // TODO - Display the error } } } } override fun onFailure(errorCodeException: ErrorCodeException) { // TODO - Display the error } }) } ``` ```java private Context context; private Controller controller; private StartAddOrUpdateResult startAddOrUpdateResult; void startAddOrUpdate() { // // 1. Invoke the controller start call // controller.startAddOrUpdate(new StartAddOrUpdateParameter(DEVICE_SERVER_SIDE_FACE), new AsyncCallback() { @Override public void onSuccess(StartAddOrUpdateResult result) { startAddOrUpdateResult = result; if (result.getAuthMethodsForActivation().contains(DEVICE_SERVER_SIDE_FACE) || result.getAuthMethodsForAuthentication().contains(DEVICE_SERVER_SIDE_FACE)) { // // 2. Initialise the FaceScan library // String productionKeyText = result.getServerSideFaceInit().getProductionKeyText(); String deviceKeyIdentifier = result.getServerSideFaceInit().getDeviceKeyIdentifier(); String faceScanEncryptionKey = result.getServerSideFaceInit().getEncryptionKey(); FaceTecSDK.initializeInProductionMode(context, productionKeyText, deviceKeyIdentifier, faceScanEncryptionKey, new FaceTecSDK.InitializeCallback() { @Override public void onCompletion(boolean initializationSuccess) { if (initializationSuccess) { // TODO - Display message to user: Start FaceScan? } else { // TODO - Display the error } } }); } } @Override public void onFailure(ErrorCodeException errorCodeException) { // TODO - Display the error } }); } ``` ::: #### Finish call For examples, click to expand the collapsible sections: - `finishAddOrUpdate(PIN, ServerSideFace)`: :::details Click to expand ```kotlin fun finishAddOrUpdate() { // User accepted: Start FaceScan. // // 3. Invoke the FaceScan activity // val sessionToken = startAddOrUpdateResult!!.serverSideFaceInit!!.sessionToken FaceTecSessionActivity.createAndLaunchSession(context, FaceTecFaceScanProcessor { sessionResult, faceTecFaceScanResultCallback -> faceTecFaceScanResultCallback.cancel() if (sessionResult.status == FaceTecSessionStatus.SESSION_COMPLETED_SUCCESSFULLY) { // // 4. Invoke the controller finish call with the result from the FaceScan. // controller.finishAddOrUpdate(DevicePinAuthParameter("1234"), DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), object : AsyncCallback { override fun onSuccess(result: FinishAuthenticationResult) { // TODO - Display successfully added/activated server-side face } override fun onFailure(errorCodeException: ErrorCodeException) { // TODO - Display error message } }) } else { // TODO - Display the error } }, sessionToken) } private fun createFaceScanData(sessionResult: FaceTecSessionResult): FaceScanData { return FaceScanData( sessionResult.faceScanBase64, sessionResult.auditTrailCompressedBase64[0], sessionResult.lowQualityAuditTrailCompressedBase64[0] ) } ``` ```java void finishAddOrUpdate() { // User accepted: Start FaceScan. // // 3. Invoke the FaceScan activity // String sessionToken = startAddOrUpdateResult.getServerSideFaceInit().getSessionToken(); FaceTecSessionActivity.createAndLaunchSession(context, new FaceTecFaceScanProcessor() { @Override public void processSessionWhileFaceTecSDKWaits(FaceTecSessionResult sessionResult, FaceTecFaceScanResultCallback faceTecFaceScanResultCallback) { faceTecFaceScanResultCallback.cancel(); if (sessionResult.getStatus() == FaceTecSessionStatus.SESSION_COMPLETED_SUCCESSFULLY) { // // 4. Invoke the controller finish call with the result from the FaceScan. // controller.finishAddOrUpdate(new DevicePinAuthParameter("1234"), new DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), new AsyncCallback() { public void onSuccess(FinishAuthenticationResult result) { // TODO - Display successfully added/activated server-side face } public void onFailure(final ErrorCodeException errorCodeException) { // TODO - Display error message } }); } else { // TODO - Display the error } } }, sessionToken); } private FaceScanData createFaceScanData(FaceTecSessionResult sessionResult) { return new FaceScanData( sessionResult.getFaceScanBase64(), sessionResult.getAuditTrailCompressedBase64()[0], sessionResult.getLowQualityAuditTrailCompressedBase64()[0]); } ``` ::: - `finishAddOrUpdate(ServerSideFace, PIN)`: :::details Click to expand This flow is identical to the `finishAddOrUpdate(PIN, ServerSideFace)` flow, however the `finishAddOrUpdate` call has swapped parameters for PIN and server-side face: ```kotlin controller.finishAddOrUpdate(DeviceServerSideFaceAuthParameter(createFaceScanData(sessionResult)), DevicePinActivationParameter("1234"), object : AsyncStateChangedCallback { ``` ```java controller.finishAddOrUpdate(new DeviceServerSideFaceAuthParameter(createFaceScanData(sessionResult)), new DevicePinActivationParameter("1234"), new AsyncStateChangedCallback() { ``` ::: - `finishAddOrUpdate(BiomtricPrompt, ServerSideFace)`: :::details Click to expand This flow is identical to the finishAddOrUpdate(PIN, ServerSideFace) flow, however but the `finishAddOrUpdate` call has `DeviceAndroidBiometricPromptAuthParameter` instead of `DevicePinAuthParameter`: ```kotlin controller.finishAddOrUpdate(DeviceAndroidBiometricPromptAuthParameter(context), DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), object : AsyncStateChangedCallback { ``` ```java controller.finishAddOrUpdate(new DeviceAndroidBiometricPromptAuthParameter(context), new DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), new AsyncStateChangedCallback() { ``` ::: - `finishAddOrUpdate(ServerSideFace, BiomtricPrompt)`: :::details Click to expand This flow is identical to the `finishAddOrUpdate(PIN, ServerSideFace)` flow, however the `finishAddOrUpdate` call has `DeviceAndroidBiometricPromptActivationParameter` instead of `DevicePinActivationParameter`: ```kotlin controller.finishAddOrUpdate(DeviceServerSideFaceAuthParameter(createFaceScanData(sessionResult)), DeviceAndroidBiometricPromptActivationParameter(context), object : AsyncStateChangedCallback { ``` ```java controller.finishAddOrUpdate(new DeviceServerSideFaceAuthParameter(createFaceScanData(sessionResult)), new DeviceAndroidBiometricPromptActivationParameter(context), new AsyncStateChangedCallback() { ``` ::: ### Authentication #### Start call For an example of `startAuthentication`, click to expand the collapsible section: :::details Click to expand ```kotlin private lateinit var context: Context private lateinit var controller: Controller private var startAuthenticationResult: StartAuthenticationResult? = null fun startAuthentication() { // // 1. Invoke the controller start call // controller.startAuthentication(object : AsyncCallback { override fun onSuccess(result: StartAuthenticationResult) { startAuthenticationResult = result if (result.authMethodsForAuthentication.contains(AuthMethod.DEVICE_SERVER_SIDE_FACE)) { // // 2. Initialise the FaceScan library // val productionKeyText = result.serverSideFaceInit!!.productionKeyText val deviceKeyIdentifier = result.serverSideFaceInit!!.deviceKeyIdentifier val faceScanEncryptionKey = result.serverSideFaceInit!!.encryptionKey FaceTecSDK.initializeInProductionMode(context, productionKeyText, deviceKeyIdentifier, faceScanEncryptionKey) { initializationSuccess -> if (initializationSuccess) { // TODO - Display message to user: Start FaceScan? } else { // TODO - Display the error } } } } override fun onFailure(errorCodeException: ErrorCodeException) { // TODO - Display the error } }) } ``` ```java private Context context; private Controller controller; private StartAuthenticationResult startAuthenticationResult; void startAuthentication() { // // 1. Invoke the controller start call // controller.startAuthentication(new AsyncCallback() { @Override public void onSuccess(StartAuthenticationResult result) { startAuthenticationResult = result; if (result.getAuthMethodsForAuthentication().contains(DEVICE_SERVER_SIDE_FACE)) { // // 2. Initialise the FaceScan library // String productionKeyText = result.getServerSideFaceInit().getProductionKeyText(); String deviceKeyIdentifier = result.getServerSideFaceInit().getDeviceKeyIdentifier(); String faceScanEncryptionKey = result.getServerSideFaceInit().getEncryptionKey(); FaceTecSDK.initializeInProductionMode(context, productionKeyText, deviceKeyIdentifier, faceScanEncryptionKey, new FaceTecSDK.InitializeCallback() { @Override public void onCompletion(boolean initializationSuccess) { if (initializationSuccess) { // TODO - Display message to user: Start FaceScan? } else { // TODO - Display the error } } }); } } @Override public void onFailure(ErrorCodeException errorCodeException) { // TODO - Display the error } }); } ``` ::: #### Finish call For an example of `finishAuthentication(ServerSideFace)`, click to expand the collapsible section: :::details Click to expand ```kotlin fun finishAuthentication() { // User has accepted: Start FaceScan. // // 3. Invoke the FaceScan activity // val sessionToken = startAuthenticationResult!!.serverSideFaceInit!!.sessionToken FaceTecSessionActivity.createAndLaunchSession(context, FaceTecFaceScanProcessor { sessionResult, faceTecFaceScanResultCallback -> faceTecFaceScanResultCallback.cancel() if (sessionResult.status == FaceTecSessionStatus.SESSION_COMPLETED_SUCCESSFULLY) { // // 4. Invoke the controller finish call with the result from the FaceScan. // controller.finishAuthentication(DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), object : AsyncCallback { override fun onSuccess(result: FinishAuthenticationResult) { // TODO - Display successfully added/activated server-side face } override fun onFailure(errorCodeException: ErrorCodeException) { // TODO - Display error message } }) } else { // TODO - Display the error } }, sessionToken) } private fun createFaceScanData(sessionResult: FaceTecSessionResult): FaceScanData { return FaceScanData( sessionResult.faceScanBase64, sessionResult.auditTrailCompressedBase64[0], sessionResult.lowQualityAuditTrailCompressedBase64[0] ) } ``` ```java void finishAuthentication() { // User has accepted: Start FaceScan. // // 3. Invoke the FaceScan activity // String sessionToken = startAuthenticationResult.getServerSideFaceInit().getSessionToken(); FaceTecSessionActivity.createAndLaunchSession(context, new FaceTecFaceScanProcessor() { @Override public void processSessionWhileFaceTecSDKWaits(FaceTecSessionResult sessionResult, FaceTecFaceScanResultCallback faceTecFaceScanResultCallback) { faceTecFaceScanResultCallback.cancel(); if (sessionResult.getStatus() == FaceTecSessionStatus.SESSION_COMPLETED_SUCCESSFULLY) { // // 4. Invoke the controller finish call with the result from the FaceScan. // controller.finishAuthentication(new DeviceServerSideFaceActivationParameter(createFaceScanData(sessionResult)), new AsyncCallback() { public void onSuccess(FinishAuthenticationResult result) { // TODO - Display successfully added/activated server-side face } public void onFailure(final ErrorCodeException errorCodeException) { // TODO - Display error message } }); } else { // TODO - Display the error } } }, sessionToken); } private FaceScanData createFaceScanData(FaceTecSessionResult sessionResult) { return new FaceScanData( sessionResult.getFaceScanBase64(), sessionResult.getAuditTrailCompressedBase64()[0], sessionResult.getLowQualityAuditTrailCompressedBase64()[0]); } ``` ::: ## Error handling The following client-side errors originate in the FaceTec SDK, and are propagated as follows: - `FaceTecSDK.initializeInProductionMode()` returns errors in `FaceTecSDK.getStatus(context)`. - `FaceTecSessionActivity.createAndLaunchSession()` returns errors in `sessionResult.getStatus()`, in the callback method `processSessionWhileFaceTecSDKWaits(FaceTecSessionResult sessionResult)`. ## Localisation The FaceTecSDK includes language resource strings prefixed with `FaceTec_`. It supports the following languages: - Afrikaans (af) - Arabic (ar) - German (de) - Greek (el) - English (en) - Spanish (es) - French (fr) - Kazakh (kk) - Norwegian (nb) - Portuguese (pt-rBR) - Russian (ru) For further details, see the `FaceTecSDK.zip` file. ## Branding and styling ### What elements can be customised? The FaceTec SDK allows you to customise various branding and styling elements, such as: - Interface - Borders - Colors - Fonts - Branding image - Button image and position - Progress - Vocal guidance sound file resources To learn more about what you can customise, see the [UX Themes Branding](https://dev.facetec.com/ui-customization) page in the FaceTec documentation. You can also refer to the `FaceTecSDK.zip` file. ### How to customise the configuration To make changes, you have to create a `FaceTecCustomization` object, where you define each field that you want to change. ### Different environmental conditions You can apply different settings based on environmental conditions, such as low-light or bright-light situations. To do this, you must set a unique configuration for each of the scenarios using the `FaceTecCustomization` object. The FaceTecSDK includes methods: - Default: ```kotlin title="Example: Default method" FaceTecSDK.setCustomization(customization: FaceTecCustomization) ``` ```java title="Example: Default method" FaceTecSDK.setCustomization(FaceTecCustomization customization); ``` - Low-light: ```kotlin title="Example: Low-light method" FaceTecSDK.setLowLightCustomization(customization: FaceTecCustomization) ``` ```java title="Example: Low-light method" FaceTecSDK.setLowLightCustomization(FaceTecCustomization customization); ``` - Bright-light: ```kotlin title="Example: Bright-light method" FaceTecSDK.setDynamicDimmingCustomization(customization: FaceTecCustomization) ``` ```java title="Example: Bright-light method" FaceTecSDK.setDynamicDimmingCustomization(FaceTecCustomization customization); ``` ## Multiple controller scenario For a multiple controller scenario, face authentication must be activated for each controller. --- ## Geofencing(Configure-features) ## About geofencing Our geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. By limiting the use of Encap SCA activations (registrations/enrolments) and authentications to certain regions​, you can reduce the chance of fraud. ## How does geofencing work? When geofencing is enabled, the client will send the country code of the location of the device to the server. The server will verify the location and limit the use of the device based on the configuration in your application configuration and what you have set as your allowed regions. ### Supported operations Geofencing is supported in activation (registration/enrolment) and authentication operations. :::CustomTable{minTableSize="800px"} | **Method/operation name** | **Mode parameter used to configure geofencing** | **Is geofencing result sent in `OPTIONAL` mode?** | | :-- | :-- | :-- | | `startActivation`, `finishActivation` | `GEOFENCING_ACTIVATION_MODE` | | | `startRecovery`, `finishRecovery` | `GEOFENCING_ACTIVATION_MODE` | | | `startAuthentication`, `finishAuthentication` | `GEOFENCING_AUTHENTICATION_MODE` | | | `startAddOrUpdate`, `finishAddOrUpdate` | `GEOFENCING_AUTHENTICATION_MODE` | | ::: :::tip Receiving the geofencing result The geofencing result is returned from the Encap server to you using the REST API. ::: ### Functionality Geofencing is configured in your application configuration, through the following mode parameters: - `GEOFENCING_ACTIVATION_MODE` - `GEOFENCING_AUTHENTICATION_MODE` The mode that geofencing is set to determines the functionality when the app calls the methods illustrated in the table above. #### For start methods The Encap server informs the client about the current geofencing mode. If geofencing is enabled (`OPTIONAL` or `REQUIRED`), then the external geocoder platform is called with location as a parameter. #### For finish methods If geofencing is enabled (`OPTIONAL` or `REQUIRED`), then the client will send a request to the server that includes the country code from the geocoder external service, or without a country code if the lookup was not successful. If there is no location on the device, then the client will wait until the timeout measured from the start method to complete. The timeout is configured on the server for location and geofencing. ## How to configure geofencing To use our geofencing feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK To configure the mobile SDK for geofencing: 1. You need to insert location permissions into the app manifest. To do this, see the [enable location](/docs/mobile-identity/encap/sdk-android/configure-features/location.mdx#enable-location) section in our location feature documentation. 2. The end-user must grant location permissions on their mobile device. ### Configure the application configuration The process for configuring the application configuration varies depending on whether you are a MobileID customer or an Encap SCA customer. You can use the buttons below to learn how to configure the application configuration for the different products. * [**Configure MobileID**](/docs/mobile-identity/mobileid/features/geofencing#configure-the-application-configuration): Learn how to configure the application configuration for geofencing * [**Configure Encap SCA**](/docs/mobile-identity/encap/features/geofencing#configure-the-application-configuration): Learn how to configure the application configuration for geofencing ## Error codes - If the geofencing mode is set to `OFF` or `OPTIONAL`, then no new error codes are introduced. - If the geofencing mode is set to `REQUIRED`, then it is possible to receive one of the errors illustrated in the table below from a finish method call. You can find the corresponding error descriptions in our [SDK error codes](/docs/mobile-identity/encap/sdk-error-codes.mdx#server-errors) documentation. :::CustomTable{columnWidths="25% 75%"} | **Error code** | **Error name** | | :-- | :-- | | 270 | `serverErrorGeofencingBoundaryValidationFailed` | | 271 | `serverErrorGeofencingClientFailure` | ::: --- ## Configure features You can find out how to configure our features in the Android SDK in our feature guides. * [**Account recovery**](/docs/mobile-identity/encap/sdk-android/configure-features/account-recovery): Allow your end-users to recover their registration without the need for reactivation * [**App attestation**](/docs/mobile-identity/encap/sdk-android/configure-features/app-attestation): Strengthen your application's security by preventing third-party use of our APIs * [**Certificate pinning**](/docs/mobile-identity/encap/sdk-android/configure-features/certificate-pinning): Use certificate pinning to validate the requests from the server * [**Client debug data**](/docs/mobile-identity/encap/sdk-android/configure-features/client-debug-data): Pass data from the client to the server for debugging purposes * [**Device groups**](/docs/mobile-identity/encap/sdk-android/configure-features/device-groups): Create groups of devices that can share a single server-side FaceMap across them * [**Face authentication**](/docs/mobile-identity/encap/sdk-android/configure-features/face-authentication): Add server-side face authentication to your app * [**Geofencing**](/docs/mobile-identity/encap/sdk-android/configure-features/geofencing): Reduce fraud by limiting the use of your app to certain regions * [**Location**](/docs/mobile-identity/encap/sdk-android/configure-features/location): Collect the location of the device for each operation * [**Operation context**](/docs/mobile-identity/encap/sdk-android/configure-features/operation-context): Send important information to your app, through our secure channel * [**Push notifications**](/docs/mobile-identity/encap/sdk-android/configure-features/push-notifications): Send push notifications using Firebase Cloud Messaging (FCM) * [**Risk parameters**](/docs/mobile-identity/encap/sdk-android/configure-features/risk-parameters): Collect risk attributes for each operation :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Location Location is one of the risk parameters that can be sent to the server. ## Enable location To enable collection of location by the Encap SDK, you need to carry out the following steps: 1. In your application configuration, ensure that `ENABLED_RISK_DATA` is set to `ALL`, or that it contains `Location`. 2. In the app manifest, ensure that the following location permissions are inserted: ```xml title="Example: Location permissions in app manifest" ``` 3. For Android 10 and higher, you should consider adding the following: ```xml title="Example: Addition for Android 10 and higher" ``` :::note Note The permission `ACCESS_BACKGROUND_LOCATION` is not necessary for foreground location collection. Be aware that this permission can be denied by the end-user. ::: The Encap SDK does not request Android system permissions. This means that the application using the Encap SDK needs to implement that request. :::info Want to learn more? To learn how to request system permissions in your application, you can follow the instructions in the [Android developer documentation](https://developer.android.com/training/permissions/requesting). ::: ## Disable location To disable location, you need to remove the following location permissions from the app manifest file: ```xml title="Example: Disable location by removing permissions" ``` ## Enable location (excluding the Encap SDK) You may have a use case where you need to disable collecting location data for the Encap SDK, but need to keep location permissions for the rest of the app. To do this, you need to: 1. Keep the location permissions in app manifest. 2. Remove `Location` from `ENABLED_RISK_DATA` in your application configuration, and/or set `locationEnabled` flag in the `EncapConfig` to false. ## Enable Google Play Services location By default, when location is enabled for the Encap SDK, the library uses the platform version of location. If you want to enable the Google Play Services location, then add the dependency to your app. Once you have done this, the library then picks it up and enables it for all supported Android versions. ```kotlin title="Example: Add dependency to your app" dependencies { implementation("com.google.android.gms:play-services-location:21.3.0") } ``` ```groovy title="Example: Add dependency to your app" dependencies { implementation "com.google.android.gms:play-services-location:21.3.0" } ``` ## Prevent SDK location update requests By default, when location permission is granted, the Encap SDK requests location updates: - Whenever an `EncapConfig` is set. - During most SDK operations. If you want to prevent the Encap SDK from requesting location updates, then you can use the `locationEnabled` flag in the `EncapConfig`. This allows you to avoid unnecessary battery consumption if your app does not use any features from the Encap SDK that rely on the device's location. :::warning Important If you disable location updates while location, geofencing, or SSID/BSSID features are enabled, then it may result in unintended behaviour. ::: --- ## Operation context You can use the operation context to add context to the activation or authentication attempt. For example, an end-user may need to authenticate themselves to allow for a certain transfer to proceed. - For activation, the Encap server can return a post-operation context. - For authentication, the Encap server can return both a pre-operation context and a post-operation context. You can find the data in the respective result classes: - `FinishActivationResult` - `StartAuthenticationResult` - `FinishAuthenticationResult` To get the full operation context, you can use the following functions on the result classes: :::CustomTable{columnWidths="25% 75%"} | **Function** | **Description** | | :-- | :-- | | `getContextTitle()`| Get the title of the context returned. | | `getContextContent()`| Get the data for the context. | | `getContextMIME()`| Get the MIME type of the data sent in context content. | ::: :::tip Note These fields can be null. ::: You can read more about operation context in our [MobileID feature documentation](/docs/mobile-identity/mobileid/features/operation-context.mdx). --- ## Push notifications(Configure-features) :::info About this documentation This documentation only describes how to configure the SDK for our push notifications feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/push-notifications/)   [**Encap**](/docs/mobile-identity/encap/features/push-notifications/) ::: ## How do push notifications work? For Android, we support the use of Firebase Cloud Messaging (FCM) push notifications to notify the end-user when an operation has started. :::info Want to learn more? To learn more about how FCM works, see the [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) page in the Android developer documentation. ::: ## Configure the SDK ### Prerequisites Before you start, you need make sure that you have set up support for FCM push notifications. This documentation assumes that the following steps have been completed: 1. [Add Firebase to your Android project](https://firebase.google.com/docs/android/setup). 2. [Set up a Firebase Cloud Messaging client on Android](https://firebase.google.com/docs/cloud-messaging/android/client) 3. Ensure that: - `FcmMessagingService` extends `FirebaseMessagingService`. - You have added the required entries for FCM to `AndroidManifest`, as described in the FCM documentation. ### 1. Add new service entry to AndroidManifest.xml Verify that you have added a new service entry on your ``AndroidManifest.xml`` file. ```xml title="Example: Add new service entry to AndroidManifext.xml" ``` ### 2. FcmMessagingService #### Set push token on the Encap controller 1. When FCM invokes the `onNewToken(newToken: String)` method of `FirebaseMessagingService`, the service should set the new push token on the `EncapController`. ```kotlin title="Example: Set push token on Encap controller" override fun onNewToken(newToken: String) { super.onNewToken(newToken) controller.config = EncapConfig.Builder(controller.config) .setPushToken(newToken) .build() } ``` ```java title="Example: Set push token on Encap controller" @Override public void onNewToken(String newToken) { super.onNewToken(newToken); controller.setConfig(new EncapConfig.Builder(controller.getConfig()) .setPushToken(newToken) .build()); } ``` 2. The `onNewToken()` method is called when a token is first generated and again if the token changes. This happens when: - The app is restored on a new device. - The end-user uninstalls/reinstalls the app. - The end-user clears app data. #### Receiving messages When FCM invokes the `onMessageReceived(remoteMessage: RemoteMessage)` of the `FcmMessagingService`: - Create an intent with the action `com.google.firebase.MESSAGING_EVENT`. - Set the intent's extra data with `remoteMessage.toIntent()`. - Send the intent to the `Activity`, either directly or via a notification with a `PendingIntent()` if the app is in the background. ```kotlin override fun onMessageReceived(remoteMessage: RemoteMessage) { val intent = Intent(this, MainActivity::class.java).apply { action = "com.google.firebase.MESSAGING_EVENT" putExtras(remoteMessage.toIntent()) } // If application is in foreground, immediately send intent to activity // Otherwise, display a notification instead if(appInForeground){ startActivity(intent) } else { displayNotification(intent) } } ``` ```java @Override public void onMessageReceived(RemoteMessage remoteMessage) { Intent intent = new Intent(this, MainActivity.class); intent.setAction("com.google.firebase.MESSAGING_EVENT"); intent.putExtras(remoteMessage.toIntent()); // If application is in foreground, immediately send intent to activity // Otherwise, display a notification instead if(appInForeground){ startActivity(intent); } else { displayNotification(intent); } } ``` ### 3. Activity 1. When the `Activity` receives an intent in `onNewIntent(Intent)` or `onCreate()`, you should examine the intent. 2. If the intent is an FCM intent with action `com.google.firebase.MESSAGING_EVENT`, then: - Create a push message of it using `PushMessageFactory.createFromIntent(Intent)`. - If the push message is a start message, then examine whether it starts an activation or authentication, and call the Encap API's corresponding start method. ```kotlin override fun onNewIntent(intent: Intent) { super.onNewIntent(intent) processIntent(intent) } private fun processIntent(intent: Intent) { try { if ("com.google.firebase.MESSAGING_EVENT" == intent.action) { // Launched from FCM. processPushMessage(intent) } else { // Your other notifications handling } } catch (ex: Exception) { Log.d(TAG, "processIntent: caught exception: ", ex) } } private fun processPushMessage(intent: Intent) { val pushMessage = PushMessageFactory.createFromIntent(intent) if (pushMessage.isStartMessage) { if (pushMessage.isActivationMessage) { // Handle activation } else if (pushMessage.isAuthenticationMessage) { // Handle authentication } else if(pushMessage.isRecoveryPerformedNotification) { // Handle recovery performed } else { Log.d(TAG, "unexpected message type") } } } ``` ```java @Override public void onNewIntent(Intent intent) { super.onNewIntent(intent); processIntent(intent); } private void processIntent(Intent intent) { try { if ("com.google.firebase.MESSAGING_EVENT".equals(intent.getAction())) { // Launched from FCM. processPushMessage(intent); } else { // Your other notifications handling } } catch (Exception ex) { Log.d(TAG, "processIntent: caught exception: ", ex); } } private void processPushMessage(Intent intent) throws java.net.URISyntaxException { PushMessage pushMessage = PushMessageFactory.createFromIntent(intent); if (pushMessage.isStartMessage()) { if (pushMessage.isActivationMessage()) { // Handle activation } else if (pushMessage.isAuthenticationMessage()) { // Handle authentication } else if(pushMessage.isRecoveryPerformedNotification()) { // Handle recovery performed } else { Log.d(TAG, "unexpected message type"); } } } ``` ::::info Detailed implementation For more details on the implementation, see the `com.encapsecurity.encap.example.android.testapp.util.FcmMessagingService` class. :::: ## Custom push payload You can send a custom payload in the push to the device. If the custom payload is sent, it can be read by creating a `PushMessage` with `PushMessageFactory.createFromIntent()` either: - In the `FcmMessagingService` class within `onMessageReceived()`. - In in the Activity within `onNewIntent()`. ```kotlin val pushMessage = PushMessageFactory.createFromIntent(intent) val payload: String? = pushMessage.customPayload ``` ```java PushMessage pushMessage = PushMessageFactory.createFromIntent(intent); String payload = pushMessage.getCustomPayload(); ``` --- ## Risk parameters ## About risk parameters Risk parameters are sent to the Encap SCA server and then passed on to you to make risk assessment possible. ## How to configure risk parameters You can enable and disable the risk parameters in the application configuration, by configuring `ENABLED_RISK_DATA`. You can get the information about what risk parameters are sent to the server by calling `getEnabledRiskParameters()`. This will return a `RiskParameterServerConfig` object. With the function `setRiskParameter()` on the `EncapController`, you can set risk parameters. Only `IS_ROOT_AVAILABLE` is available for the app to set currently. :::info Want to learn more? For a complete list of the data that is collected by this feature, see the [Optionally collected data](/docs/mobile-identity/encap/sdk-android/publish-your-app/collected-data.mdx#optionally-collected-data) section in our **Collected data** appendix. ::: ### Rooting status There is no default value for this parameter, so if the app does not call this function, the rooting status is not passed on to the server. The app is free to implement the rooting detection as desired; either by its own implementation, or with a third-party library such as Promon SHIELD®. ### Wi-Fi information (SSID and BSSID) The SDK can be configured to collect the SSID (network name) and BSSID (network hardware address) of the Wi-Fi network to which the device is connected. This information can be a valuable component in risk assessment. For example, this can identify whether the end-user is on a known, trusted network. To enable the collection of this data, the following two conditions must be met: :::warning Important If either of these requirements are not met, then the SSID and BSSID are not collected or sent to the server. ::: - **Developer configuration**: You must add the following permissions to your application's `AndroidManifest.xml` file, so that the SDK can access the relevant Wi-Fi information: ```xml title="Required permissions in AndroidManifest.xml" ``` - **End-user permission**: The end-user of the application must have granted location permissions for the app. Google requires location services to be enabled for an app to retrieve Wi-Fi network details. --- ## Core operations ## Introduction On this page, you can learn about the different core operations that you can make with the SDK. The activate and authentication processes are divided into multiple steps, which are performed as individual method calls on a controller. Most calls are asynchronous, and the application is required to provide a block of code to be executed once each call has finished. ## Activation ### Overview Activation is the first thing that your application will guide your end-user through when using Encap. This process creates a link between your end-user's device and the Encap authentication server. This will later be used to establish trust. To activate the end-user's device, your application will invoke three methods on the `Controller` in succession. The process is as follows: 1. **Optional**: Retrieve settings from the Encap server, such as activation code length and type. 2. Register the end-user's device on Encap server. The Encap server will then pass information back which the API will use to establish trust. 3. Activate the registration, using a selected authentication method and the information that was passed back in the previous step. :::tip Note Following these steps, the registration can now be used to authenticate the end-user that created it. ::: ### How to implement #### Retrieve settings from Encap server (optional) To begin the process, you can invoke `loadConfig()`. :::tip Note It will return a LoadConfigResult object with information about the activation code length and type, so that the app can present the right keyboard and UI to be input. Although this call is optional, it can improve the end-user's experience. ::: #### Register the end-user's device on the Encap server 1. Run the `startActivation()` operation. 2. If the `startActivation()` operation is successful, then a `StartActivationResult` object is returned. This contains `getAuthMethodsForActivation()`, which is a list of authentication methods (`AuthMethod`) available for the device. - The list of authentication methods is filtered so that only those configured for this `applicationId` and enabled on the device are returned. - If more than one method is available, your app may let the end-user choose what authentication method to use. #### Activate the registration Once the `startActivation()` operation has been completed successfully, you can finish the process. To do this, run the `finishActivation()` operation with the desired authentication method. Use the correct type of `ActivationParameter` for the authentication method, and fill in the required data. :::tip Explore supported authentication methods For supported authentication methods and additional details, see the [Authentication methods](/docs/mobile-identity/encap/sdk-android/authentication-methods.mdx) page in our Encap SDK developer documentation. ::: :::tip Note The device as an authentication method (`AuthMethod.DEVICE`) will always be activated when activating a two-factor authentication method, such as PIN and Biometric Prompt. ::: ```kotlin title="Example: An activation" // The activation code should come from another source, such as a web page. controller.startActivation(activationCode, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartActivationResult) { // Ready to continue to finishActivate. See result on how to proceed. val activationParameter = ActivationParameter() // Use the right type here for the auth method you want. controller.finishActivation(activationParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishActivationResult) { // The auth method is activated. } }) } }) ``` ```java title="Example: An activation" // The activation code should come from another source, such as a web page. controller.startActivation(activationCode, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartActivationResult result) { // Ready to continue to finishActivate. See result on how to proceed. ActivationParameter activationParameter = new ActivationParameter(); // Use the right type here for the auth method you want. controller.finishActivation(activationParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishActivationResult result) { // The auth method is activated. } }); } }); ``` #### Fetch the registrationId After a successful activation, the `registrationId` is stored on the controller. ```kotlin title="Example: Fetch the registrationId" controller.registrationId( appCallback = object: AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) {...} override fun onSuccess(result: String) {val registrationId = result} }) ``` ```java title="Example: Fetch the registrationId" controller.registrationId( new AsyncCallback() { override fun onFailure(errorCodeException: ErrorCodeException) {...} override fun onSuccess(result: String) {val registrationId = result} }) ``` :::tip Note The `registrationId` is the same as the `deviceId` and `device_id` which is used in the REST APIs. ::: ## Authentication ### Overview Authentication is a process used to prove that the current end-user is the same as the one who performed the initial activation. To authenticate the end-user, your application will invoke two methods on the `Controller` in succession. The process is as follows: 1. Identify who your end-user claims to be to the Encap server. 2. The Encap server sends a challenge to the client API and a response is calculated. 3. If the authentication succeeds, then the Encap server has indicated trust that you are interacting with the correct end-user. ### How to perform an authentication #### Start the authentication To begin the process, you need to run the `startAuthentication()` operation. If the `startAuthentication()` operation is successful, then a `StartAuthenticationResult` object is returned. This has the following methods: :::CustomTable{columnWidths="50% 50%"} | **Method** | **Description** | | :-- | :-- | | `getAuthMethodsForAuthentication()` | A list of authentication methods that you can use for this operation. The list of authentication methods is filtered so that only those configured for this `applicationID`, enabled on the device and activated are returned. | | `getServerConfiguredAuthMethods()` | A list of authentication methods configured in the `applicationId`. This list is not filtered based on the capabilities of the mobile device, nor on what authentication methods are activated. **Example**: You could use this to see check if the user has forgotten to add fingerprints on the phone. | ::: #### Finish the authentication 1. Once the `startAuthentication` operation has been completed successfully, you can finish the process by running the `finishAuthentication()` operation. - You have to pass in the desired `AuthParameter` for one of the authentication methods returned from `getAuthMethodsForAuthentication()`. 2. If the authentication operation is successful, then a `FinishAuthenticationResult` object is returned. ```kotlin title="Example: An authentication" controller.startAuthentication(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAuthenticationResult) { // Ready to continue to finishAuthenticate. See result on how to proceed. val authParameter = AuthParameter() // Use the right type here for the auth method you want. controller.finishAuthentication(authParameter, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // Successfully authenticated with auth method. } }) } }) ``` ```java title="Example: An authentication" controller.startAuthentication(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAuthenticationResult result) { // Ready to continue to finishAuthenticate. See result on how to proceed. AuthParameter authParameter = new AuthParameter(); // Use the right type here for the auth method you want. controller.finishAuthentication(authParameter, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // Successfully authenticated with auth method. } }); } }); ``` ## Add or update ### Overview The `addOrUpdate` operation enables you to: - Add (activate) another authentication method to an existing registration. - Update an existing authentication method using the same authentication method. This is a special use case for updating the PIN. ### Example use case Your end-user wants add another authentication method to their existing registration. For example, they want to activate both the PIN and the Biometrics authentication methods. To do this, you could: 1. Activate the first authentication method (PIN) as described in the [PIN activation](/docs/mobile-identity/encap/sdk-android/authentication-methods.mdx#add-or-update-change-pin) section on our **Authentication methods** page. 2. Activate the second authentication method (Biometrics) from within your app using the `addOrUpdate` operation. ### How to implement #### Add another authentication to an existing registration 1. Activate the PIN as described in the [PIN activation](/docs/mobile-identity/encap/sdk-android/authentication-methods.mdx#add-or-update-change-pin) section on our **Authentication methods** page. 2. The end-user activates Biometrics in your app by calling `startAddOrUpdate`. 3. If the operation is successful, then a `StartAddOrUpdateResult` object is returned, similar to the result from the `StartAuthentication()` operation. 4. Use the `getAllowedAuthMethodsToActivate()` parameter to select which authentication method to add, and look at `getAllowedAuthMethodsForAuthentication` to find an authentication method that is supported for authenticating in this case. 5. Once the start call has been successfully executed, call `finishAddOrUpdate` with the `AuthParameter` for the authentication method that you want to authenticate with, and the `ActivationParameter` for the authentication method you want to activate. :::tip Find activation and authentication parameters To find the right activation parameters (`ActivationParameter`) and authentication parameters (`AuthenticationParameter`), see the [Authentication methods](/docs/mobile-identity/encap/sdk-android/authentication-methods.mdx) page in our Encap SDK developer documentation. ::: 6. Upon a successful result, the new authentication method has now been activated and is ready to be used to authenticate the end-user. :::tip Note A single-factor authentication method cannot be used to add a two-factor authentication method. You need to configure on the server which two-factor authentication methods can be used to add other two-factor authentication methods. ::: :::tip Other use cases Another common use case is to update the end-user's PIN. You can read more about this in the [Add or update (change PIN)](/docs/mobile-identity/encap/sdk-android/authentication-methods.mdx#add-or-update-change-pin) section on our **Authentication methods** page. ::: ```kotlin title="Example: An add or update" controller.startAddOrUpdate(StartAddOrUpdateParameter(), object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: StartAddOrUpdateResult) { // Ready to continue to finishAuthenticate. See result on how to proceed. val authParameter = AuthParameter() // Use the right type here for the auth method you want. val activationParameter = ActivationParameter() // Use the right type here for the auth method you want. controller.finishAddOrUpdate(authParameter, activationParameter, object : AsyncStateChangedCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: FinishAuthenticationResult) { // Successfully added auth method to registration. } override fun onStateChanged(state: EncapController.State) { // Possibility to update UI. } }) } }) ``` ```java title="Example: An add or update" controller.startAddOrUpdate(new StartAddOrUpdateParameter(), new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(StartAddOrUpdateResult result) { // Ready to continue to finishAuthenticate. See result on how to proceed. AuthParameter authParameter = new AuthParameter(); // Use the right type here for the auth method you want. ActivationParameter activationParameter = new ActivationParameter(); // Use the right type here for the auth method you want. controller.finishAddOrUpdate(authParameter, activationParameter, new AsyncStateChangedCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(FinishAuthenticationResult result) { // Successfully added auth method to registration. } public void onStateChanged(EncapController.State state) { // Possibility to update UI. } }); } }); ``` ## Deactivate ### Overview The `Controller` provides two different deactivation methods. - Deactivate all authentication methods. This could be useful if: - Your end-user no longer wants to have an account in your app and wants their data deleted. - Deactivate a specified authentication method. This could be useful if: - Your end-user no longer wants to use Biometrics. Your app could then allow the end-user to deactivate that authentication method. - Your app no longer wants to support an authentication method. Your app could then call deactivate on that authentication method method. **Note**: Typically, you may consider to rewrite the app instead, so that this does not end up in the flow. You may require deactivation or reactivation if the end-user forgets the PIN from their first activation. The scenario will then be identical to that of a first time activation. ### How to implement #### Deactivate the registration Run the deactivate method to delete all registration data for the given registration, including all of the authentication methods. - If the `localOnly` parameter is set to false, then the registration is removed both from the Encap server and locally. - If the `localOnly` parameter is set to true, then the registration will only be removed locally. :::tip Our recommendation It is advised to always try to deactivate towards the server. If the server is down or an other abnormality prevents you from deactivating towards the server, you can perform a local deactivation as a fallback. ::: ```kotlin title="Example: A deactivation" val deactivateOnlyLocally = false controller.deactivate(deactivateOnlyLocally, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: DeactivateResult) { // Successfully deactivated. } }) ``` ```java title="Example: A deactivation" final boolean deactivateOnlyLocally = false; controller.deactivate(deactivateOnlyLocally, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(DeactivateResult result) { // Successfully deactivated. } }); ``` #### Deactivate a specified authentication method 1. Run the `deactivate(AuthMethod,...)` method to deactivate a specific authentication method. The registration will stay intact. 2. The specified authentication method (`authMethod`) is removed both from the Encap server and locally. :::tip Limitations The device as an authentication method (`AuthMethod.DEVICE`) is used for authentication towards the server, and cannot be deactivated by this method. ::: ```kotlin title="Example: Deactivate a specified authentication method" controller.deactivate(AuthMethod.DEVICE_PIN, object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: DeactivateResult) { // Successfully deactivated. } }) ``` ```java title="Example: Deactivate a specified authentication method" controller.deactivate(AuthMethod.DEVICE_PIN, new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(DeactivateResult result) { // Successfully deactivated. } }); ``` ## Cancel session ### Overview You can use the `cancelSession` operation to cancel the activation or authentication session on the server. For example, you could use this when the client has been notified of a new transaction, but the user rejects it by pressing the cancel button. ### How to implement 1. Run the `cancelSession()` operation. 2. The current activation or authentication session will now be cancelled on the server. ```kotlin title="Example: Cancel a session" controller.cancelSession(object : AsyncCallback { override fun onFailure(errorCodeException: ErrorCodeException) { // Handle the failure. } override fun onSuccess(result: CancelSessionResult) { // Successfully cancelled session. } }) ``` ```java title="Example: Cancel a session" controller.cancelSession(new AsyncCallback() { public void onFailure(ErrorCodeException errorCodeException) { // Handle the failure. } public void onSuccess(CancelSessionResult result) { // Successfully cancelled session. } }); ``` --- ## Getting started ## Prerequisites Before you can get started, you must first install the following software: - Android studio from the [Android developer documentation](https://developer.android.com/studio). - Java Development Kit 17 (JDK) from the [Oracle website](https://www.oracle.com/java/technologies/downloads/). ### Recommended Kotlin version The SDK is made using **Kotlin 2.2**. If your app uses Kotlin, then we recommend that you use a language version that is the same (**2.2**) or newer. The Kotlin binary format is often forwards compatible with the next Kotlin language release, but not later ones. Although this means that the minimum supported Kotlin language version is generally one version prior (**2.1**), we cannot guarantee compatibility. ### Minimum Android version The minimum supported Android version for the Encap SDK is **Android 9.0 (API level 28)**. ## Add the SDK to your application :::tip Note The Encap SDK is available from our repository. The repository is gated, therefore you require login credentials to access it. ::: You need to add the Encap client API to the application using Android studio and Gradle. To do this: 1. Request your Nexus repository login credentials from us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. 2. Once you have obtained access, you can set your Nexus repository login credentials: 1. Navigate to `$HOME/.gradle/gradle.properties`. 2. Set the following credentials: ```properties title="Example: Set your Nexus repository login credentials" mavenUser= mavenPassword= ``` 3. Add Encap as dependency in your app's `build.gradle` file: ```kotlin title="Example: Add Encap as a dependency" dependencies { implementation("com.encapsecurity:encap-android-api:3.22.5@aar") } ``` ```groovy title="Example: Add Encap as a dependency" dependencies { implementation "com.encapsecurity:encap-android-api:3.22.5@aar" } ``` 4. Add Encap as a custom repository in your project's `build.gradle` file. - For Encap SCA customers: ```kotlin title="Example: Add Encap as a custom repository" allprojects { repositories { maven { credentials { username = providers.gradleProperty("mavenUser").get() password = providers.gradleProperty("mavenPassword").get() } url = uri("https://nexus.pub.encap.no/content/repositories/encap-partner-repository") } } } ``` ```groovy title="Example: Add Encap as a custom repository" allprojects { repositories { maven { credentials { username mavenUser password mavenPassword } url "https://nexus.pub.encap.no/content/repositories/encap-partner-repository" } } } ``` - For MobileID customers: ```kotlin title="Example: Add Encap as a custom repository" allprojects { repositories { maven { credentials { username = providers.gradleProperty("mavenUser").get() password = providers.gradleProperty("mavenPassword").get() } url = uri("https://nexus.pub.encap.no/content/repositories/MobileID-partner") } } } ``` ```groovy title="Example: Add Encap as a custom repository" allprojects { repositories { maven { credentials { username mavenUser password mavenPassword } url "https://nexus.pub.encap.no/content/repositories/MobileID-partner" } } } ``` ## Load the library Before you can use the library, it needs to be loaded. You need to do this in a way where the library is only loaded once. For example, you could implement this using the following code: ```kotlin title="Example: Load the library" class MyApp : Application() { companion object { init { System.loadLibrary("encap-android-native-api") } } } ``` ```java title="Example: Load the library" public class MyApp extends Application { static { System.loadLibrary("encap-android-native-api"); } } ``` ## Create a controller The main interface of the Encap client API is the `Controller`. Many of the operations that you can execute with the controller are comprised of a start and finish call. For example `startActivation()` and `finishActivation()`. You can obtain the Encap controller instance using `AndroidControllerFactory` or `AndroidLoggingControllerFactory`, which are based on a singleton pattern. There can only be one instance of a specific controller with a certain name. The first call will always create a controller. Any other calls after that will return the previously created instance. The `Controller` can be created using `AndroidControllerFactory`: ```kotlin title="Example: Create a controller" val controller = if (DEBUG) { AndroidLoggingControllerFactory.getInstance(baseContext, "BankOne") } else { AndroidControllerFactory.getInstance(baseContext, "BankOne") } ``` ```java title="Example: Create a controller" EncapController controller; if (DEBUG) { controller = AndroidLoggingControllerFactory.getInstance(getBaseContext(), "BankOne"); } else { controller = AndroidControllerFactory.getInstance(getBaseContext(), "BankOne"); } ``` The log produced by `AndroidLoggingControllerFactory` in the code example above is available using standard Android tools. For example, you could use the `logcat` tool, with tag `Encap` and a message level of `INFO`. :::warning Notice for production For production, you should use the no-logging factory `AndroidControllerFactory` and optimise/obfuscate the application so that unused classes are removed. ::: :::note Note After creating the controller, the app must check that the [controller state](/docs/mobile-identity/encap/sdk-android/appendix/controller-state.mdx) is `READY` or `ERROR_INITIALIZING` before attempting to do any operations such as `isActivated` on the controller. ::: :::note Note Controllers do not share any information between themselves, so it is not possible to perform registration migrations. A created registration will only be available on the specified controller which is identified by a name. ::: ## Configure the controller To configure the controller, you need to create a new instance of `EncapConfig`, and set that on the controller. There are three properties that you always need to set, whereas the other properties are optional. :::CustomTable{columnWidths="20% 70% 10%"} | **Properties** | **Description** | **Required** | | :-- | :-- | :-- | | `serverURL` | The URL of the Encap server. | | | `applicationId` | The identifier for your application configuration. This contains specific settings for your app. | | | `publicKeyBase64` | The public key used for end-to-end encrypted communication. This is Base64 of the [DER encoded](https://en.wikipedia.org/wiki/X.690#DER_encoding) public key. To find out how to generate a valid key pair, see the [Managing E2E using the REST API](/docs/mobile-identity/encap/server/manual/server-configuration/#managing-e2e-keys-using-the-rest-api) section on the Encap **Server configuration** page. **Note**: Supports X25519 key type. | | | `publicKeyHashes` | For details, see our [Certificate pinning](/docs/mobile-identity/encap/sdk-android/configure-features/certificate-pinning.mdx) feature documentation. | | | `connectionTimeout` | The amount of time in seconds before the connection the Encap server times out. This value will be set both for connection time out as well as read time out. **Default value**: `20` seconds | | | `pushToken` | The FCM push token to be used by the server to send push messages. | | | `allowDebugData` | For details, see our [Client debug data](/docs/mobile-identity/encap/sdk-android/configure-features/client-debug-data.mdx) feature documentation. **Default value**: `true` | | | `locationEnabled` | For details, see our [Location](/docs/mobile-identity/encap/sdk-android/configure-features/location.mdx) feature documentation. **Default value**: `true` | | ::: ```kotlin title="Example: Configure the controller" controller.config = EncapConfig( serverUrl = "https://serverurl.com", // Required applicationId = "MyApplicationId", // Required publicKeyBase64 = E2EE_KEY, // Required connectionTimeout = 20000, isClientOnly = false, publicKeyHashes = hash, pushToken = token, allowDebugData = true, locationEnabled = true, ) ``` ```java title="Example: Configure the controller" controller.setConfig(new EncapConfig.Builder() .setServerUrl("https://serverurl.com") // Required .setApplicationId("MyApplicationId") // Required .setPublicKeyBase64(E2EE_KEY) // Required .setConnectionTimeout(20000) .setClientOnly(false) .setPublicKeyHashes(hash) .setPushToken(token) .setAllowDebugData(true) .setLocationEnabled(true) .build()); ``` :::note MobileID customers For MobileID customers, you must configure the following properties in the controller. This applies to both sandbox and production accounts: - `serverURL`: This is always `https://api.signicat.com/encore/encap`. - `applicationId`: To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. - `publicKey`: To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. ::: --- ## Android SDK(Sdk-android) The Encap client API hides the complexity of authenticating users and exposes a simple step-based API for your application to implement. ## How does it work? 1. Your application initiates an API call to begin the process. 2. Your application handles requests from the API by honouring and responding to them through additional API calls. ## Get started * [**Getting started**](/docs/mobile-identity/encap/sdk-android/getting-started): Learn how to set up and get started with our Android SDK * [**Core operations**](/docs/mobile-identity/encap/sdk-android/core-operations): Read about the different core operations that you can do with our SDK * [**Authentication methods**](/docs/mobile-identity/encap/sdk-android/authentication-methods): Read about the different authentication methods that we support * [**Configure features**](/docs/mobile-identity/encap/sdk-android/configure-features/): Learn how to configure the different features that we offer in the mobile SDK * [**Publish your app**](/docs/mobile-identity/encap/sdk-android/publish-your-app/): Find guidelines for a successful app release ## Support * [**Appendices**](/docs/mobile-identity/encap/sdk-android/appendix/): Read about frequently asked questions, corner cases and recommendations * [**Error codes**](/docs/mobile-identity/encap/sdk-error-codes): See an overview of all errors that could occur when using our SDK :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Collected data On this page, you can learn about all data that is collected by the Android SDK and sent to the Encap server. ## Always collected data The values in this table are always collected and sent to the Encap server. This means that you cannot configure whether this data is collected or not. :::CustomTable{tableName="Always collected data" columnWidths="25% 50% 25%"} | **Data**| **Description** | **Example** | | :-- | :-- | :-- | | Device hash | The SHA256 hash of a universally unique identifier (UUID) derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. **Note**: You can read more about the device hash in our [Device hash](/docs/mobile-identity/encap/sdk-android/appendix/device-hash.mdx) appendix. | | | Encap SDK version | The Encap SDK version used by the application. | `3.19.0-413-gc7398a6ba` | | Operating system type | The operating system type of the mobile device. | `Android` | ::: ## Optionally collected data The values in this table are optionally collected and sent to the Encap server. This means that you can configure whether the data is collected or not. To do this, you must enable the risk attribute. For further information, see `enabledRiskData` in the application configuration. :::CustomTable{tableName="Optionally collected data" columnWidths="25% 50% 25%"} | **Data**| **Description** | **Example** | | :-- | :-- | :-- | | Application hash | A SHA-256 hash of the application. | | | Battery level | The battery level of the mobile device, given as a percentage. | | | Device fingerprint | A string that identifies the mobile device's build. | | | Device model | The model name of the mobile device. | | | Device manufacturer | The manufacturer of the mobile device. | | | Geofencing | The geofencing status and country code. | | | Input method | The input method that was used to enter text in the application. You can use this to detect when a custom keyboard is being used on the mobile device. **Note**: See [Create an input](https://developer.android.com/develop/ui/views/touch-and-input/creating-input-method) in the Android developer documentation for details. | | | Is debuggable | Indicates whether the application running can be debugged using a source-level debugger, by manifest entry. **Note**: Looks for `android:debuggable=true` in the manifest. | | | Is debug enabled | Indicates whether debug is enabled on the mobile device, either by: The end-user setting (USB-debugging enabled). Running in emulator (debugging enabled by default). | | | Is debugger connected | Indicates whether a debugger is connected to the application. | | | Is developer mode | Indicates whether the developer settings are enabled on the device. | | | Is emulator | Indicates whether the application is running in an emulator. | | | Is overlay detected | Indicates whether a screen overlay is detected on the device. | | | Location | The mobile device's location, including the latitude, longitude, altitude and accuracy. | | | Gravity | An array containing gravity force measurements with timestamp from the device's gravity sensor. | 
`[``  {``    "x": 1.0,``    "y": 2.0,``    "z": 3.0,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  },``  {``    "x": 1.1,``    "y": 2.1,``    "z": 3.1,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  }``]`
| | Magnetometer | An array containing magnetic field strength measurements with timestamp from the device's magnetometer sensor. | | | Barometer | An array containing atmospheric pressure measurements with timestamp from the device's barometer sensor. | 
`[``  {``    "value": 1.0,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  },``  {``    "value": 1.1,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  }``]`
| | Time zone | The current time zone setting of the device. | | | Locale | The current locale or language setting of the device. | | | Network interface | An entry containing the client network interface. This includes the IP address and the type of the network, which can be either: `Cellular` `Wifi` `Bluetooth` `Ethernet` `Vpn` `Wifi aware` `Lowpan` `Usb` `Thread` `Satellite` | | | Operating system version | The operating system version of the mobile device. | | | Power connected status | A Boolean value which indicates whether the mobile device is being charged or is connected to a charger. | | | Root status | A Boolean value which indicates whether the mobile device has been rooted. | | | Secure screen lock status | A Boolean value which indicates whether the mobile device has secure screen enabled. **Note**: This means that the end-user has enabled either biometric or passcode authentication for unlocking their mobile device. | | | Signer hashes | A SHA-256 hash of the public key, certificate, and application signer. If there are more signers, then each hash is comma-separated. **Note**: You can use this to detect whether the application has been re-signed. | | | User agent | The HTTP User-Agent as reported from the mobile device application. | | | SSID (Base64 encoded) | Name of the Wi-Fi network that the device is connected to. **Note**: Requires location and [ACCESS_WIFI_STATE](https://developer.android.com/reference/android/Manifest.permission#ACCESS_WIFI_STATE) permissions. | `signicat-guest (Base64: c2lnbmljYXQtZ3Vlc3Q=)` | | BSSID | MAC address of the connected Wi-Fi access point. **Note**: Requires location and [ACCESS_WIFI_STATE](https://developer.android.com/reference/android/Manifest.permission#ACCESS_WIFI_STATE) permissions. | `00:14:22:01:23:45` | | VPN | A Boolean value which indicates whether the mobile device is connected to a VPN. | | | Proxy | A Boolean value which indicates whether the mobile device is connected to an HTTP/HTTPS Proxy. | | ::: ## Client debug data The values in this table are only collected and sent to the Encap server if both: - `allowDebugData` is enabled in the `EncapConfig`. - Client debug data is enabled in your application configuration. :::CustomTable{tableName="Client debug data" columnWidths="25% 50% 25%"} | **Data** | **Description** | **Example** | | :-- | :-- | :-- | | `diskSpace` | The amount of space left on the mobile device's main storage, given in MB. | `4613` | | `availableMemory` | The amount of memory left on the mobile device, given in MB. | `566` | | `processId` | The process ID of the app performing the operation. | `4247` | | `threadId` | The thread ID performing the operation. | `1172` | | `batterySaver` | A Boolean value that indicates whether the mobile device is currently in battery saver mode. | `false` | | `connectionType` | Indicates whether the operation is performed over a Wi-Fi or a cellular connection. This value can be either: `wifi` `cellular` `bluetooth` `ethernet` `vpn` `wifi aware` `lowpan` `usb` `thread` `satellite` | `wifi` | | `clientRequestTime` | The timestamp of the request as reported from the mobile device. Returned in pattern `HH:mm:ss.SSS`. | `10:36:26.160` | ::: ## Client error reporting data The values in this table are collected when an unexpected error in the Encap SDK is reported. :::note Note Only errors occurring internally in the Encap SDK with the following client codes are reported: - `clientErrorStorage` - `clientErrorUnexpected` ::: :::CustomTable{tableName="Client error reporting data" columnWidths="25% 50% 25%"} | **Data** | **Description** | **Example** | | :-- | :-- | :-- | | `id` | An identifier derived from the registration ID of the Encap controller. | `o9AzVGHiaSZDwqE25/YqLyky4gYI1R3TKQOiokbDlMA=` | | `registrationId` | The registration ID of the Encap controller. | `457302d4-51f7-49a2-8f9b-1b8f8d8e7e75` | | `clientErrorCode` | The client error code associated with the error from the Encap SDK. | `172` | | `osErrorCode` | The underlying operating system error code associated with the client error. **Note**: Currently, this value is always `-1`. | `-1` | | `stackTrace` | The stacktrace of the error from the Encap SDK. | `` | | `customMessage` | A detailed message of the error from the Encap SDK. | `commit() failed after 3 attempts` | | `isPhoneLocked` | A Boolean value which indicates whether the mobile device is locked when the client error occurs. | `false` | | `operationState` | The controller operation state at the moment when the client error occurs. When the error occurs during a moment of transition between two operation states, the original state is considered. **Note**: You can read more about this in our [Controller state](/docs/mobile-identity/encap/sdk-android/appendix/controller-state.mdx) appendix. | `PROCESSING_FINISH_ACTIVATION` | | `applicationState` | The current app lifecycle state at the moment when the client error occurs. For this value to be populated, the context provided to the SDK must implement the [LifecycleOwner](https://developer.android.com/reference/androidx/lifecycle/LifecycleOwner) interface. **Note**: Possible values are defined in [Lifecycle.State](https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State). | `RESUMED` | | `clientTimestamp` | The timestamp of the moment when the client error occurs, as reported from the mobile device. This value represents the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. | `1772556557310` | | `deviceModel` | The model name of the mobile device. | `sdk_gphone16k_arm64` | | `deviceManufacturer` | The manufacturer of the mobile device. | `Google` | | `deviceHash` | The SHA256 hash of a universally unique identifier (UUID) derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. **Note**: You can read more about this in our [Device hash](/docs/mobile-identity/encap/sdk-android/appendix/device-hash.mdx) appendix. | `SzQaI2zj+54ATPbbxFkTvetDMkJJ5FKhSGgaXEeRXJc=` | | `sdkVersion` | The Encap SDK version used by the application. | `3.22.0-312-g4e4658595` | | `osVersion` | The operating system version of the mobile device. | `16` | ::: --- ## Data safety form (Play Console) :::warning Important information This guide describes how to complete the Data safety form based **only** on how our SDK collects data. If your application collects more data than this, or handles the data differently, then you need to ensure that this is reflected correctly in the answers that you provide. ::: ## About the Data safety form Google outline that you must complete the **Data safety form** on the **App content** page in the Play Console so that you can inform Google about your app's privacy and security practices: > All developers must declare how they collect and handle user data for the apps they publish on Google Play, and provide details about how they protect this data through security practices like encryption. This includes data collected and handled through any third-party libraries or SDKs used in their apps. You can read more about this in [Google's developer documentation](https://support.google.com/googleplay/android-developer/answer/10787469?hl=en). This information is displayed on you application's Play Store listing to help your end-user's understand how you collect and share data. ## How to complete the Data safety form 1. Open Play Console, then navigate to the **App content** page under the **Policy** section. 2. Under **Data safety**, then click **Start**. :::tip Useful information - Before you start the form, read the **Overview** section. This section provides information about the questions in the form and the information that you need to provide. - Once you have read the overview, select **Next** to move on to the next section. ::: ## Data collection and security In the **Data collection and security** section, you must review the list of required user data types that you need to disclose. - For question **Does your app collect or share any of the required user data types?**, select **Yes**. - For question **Is all of the user data collected by your app encrypted in transit?**, select **Yes**. - For question **Which of the following methods of account creation does your app support?**, select **No account creation**. :::warning Other types of account creation If your application integrates other types of account creation alongside the Encap SDK, then you must check the relevant box for it here. ::: - For point **Add a link that users can use to request that their account and associated data is deleted**, you can provide a link if you selected an option in the previous question. If not, then you must select **No**. ## Data types In the **Data types** section, you must select all of the user data types that are collected or shared by your app. These data types are relevant to the risk parameters that are possible to enable in your application configuration. - You must complete the **Device or other IDs** data type, as the `deviceHash` is always collected. - The other data types are optional, as they have to be enabled in the application configuration that your app is configured to use. - If none of the optional fields are enabled, then you can skip these sections. - For all other data types not mentioned below, you must leave the fields empty if they do not apply to your application. ### Location :::tip Optional You only need to complete this section if it is enabled in the application configuration that your app is configured to use. ::: The following points are applicable if you have the **Location** or **Geofencing** risk parameters enabled: - If `android.permission.ACCESS_COARSE_LOCATION` exists in `AndroidManifest.xml`, then tick **Approximate location**. - If `android.permission.ACCESS_FINE_LOCATION` exists in `AndroidManifest.xml`, then tick **Precise location**. - If both permissions are present, then select both options. ### App info and performance :::tip Optional You only need to complete this section if it is enabled in the application configuration that your app is configured to use. ::: If the `batteryLevel` risk parameter is enabled, then tick **Diagnostics**. ### Device or other IDs The `deviceHash` is always collected, therefore you must tick **Device or other IDs**. You can read more about the device hash in our [Device hash](/docs/mobile-identity/encap/sdk-android/appendix/device-hash.mdx) appendix. ## Data usage and handling In the **Data usage and handling** section, you must answer questions about how the data is used and handled for each user data type that your app collects or shares. You can do this by clicking **Start** next to each user data type. ### Location :::tip Optional You only need to complete this section if it was applicable in the previous section. ::: - For question **Is this data collected, shared, or both?**, select **Collected**. - For question **Is this data processed ephemerally?**, select **No, this collected data is not processed ephemerally**. - For question **Is this data required for your app, or can users choose whether it's collected?**, select **Users can choose whether this data is collected**. - For question **Why is this user data required?**, select **App functionality**. ### Diagnostics :::tip Optional You only need to complete this section if it was applicable in the previous section. ::: - For question **Is this data collected, shared, or both?**, select **Collected**. - For question **Is this data processed ephemerally?**, select **No, this collected data is not processed ephemerally**. - For question **Is this data required for your app, or can users choose whether it's collected?**, select **Data collection is required (users can't turn off this data collection)** - For question **Why is this user data required?**, select **Fraud prevention, security, and compliance**. ### Device or other IDs - For question **Is this data collected, shared, or both?**, select **Collected**. For question **Is this data processed ephemerally?**, select **No, this collected data is not processed ephemerally**. - For question **Is this data required for your app, or can users choose whether it's collected?**, select **Data collection is required (users can't turn off this data collection)** - For question **Why is this user data required?**, select **App functionality**. ## How to submit the Data safety form 1. Preview the information that will be shown to end-users on Google Play in the **Store listing preview**. 2. Once you are ready to submit your completed form, select **Submit**. --- ## Publish your app This page contains guidelines to help you deliver a successful, secure and compliant app release on the **Google Play Store**, whilst avoiding common pitfalls. ## Automatic protection service If you are using Promon SHIELD® for your app security, then do not enable the **automatic protection** service or similar app protection features in the Google Play Console. :::info What does this mean? Promon SHIELD® provides more robust protection against unauthorised access and modification than what the automatic protection service offers. If activated, it adds files to your app bundle that conflict with the Promon SHIELD® repackaging detection. This can cause app crashes and submission errors. ::: ## Data safety form Before you publish, you need to ensure that your app's **Data safety form** accurately reflects the data collected and handled by both your app and our SDK. You can use the buttons below to learn how to complete the form and to see what data is collected: * [**Data safety form**](/docs/mobile-identity/encap/sdk-android/publish-your-app/data-safety-form): Learn how to complete Google Play's Data safety form * [**Collected data**](/docs/mobile-identity/encap/sdk-android/publish-your-app/collected-data): See overview of collected device and app data when using our SDK --- ## SDK error codes ## Client errors The table below lists all errors that are triggered from the Encap SCA SDK. We refer to these as **client errors**. :::CustomTable{tableName="Client error codes" columnWidths="10% 20% 15% 55%"} | Code | Error name | Applicable platforms | Description | | :-- | :-- | :-- | :-- | | `100` | `clientErrorOperationInProgress` | Android, iOS | Another operation is in progress. Wait for it to finish before issuing new requests. | | `101` | `clientErrorConnectionFailure` | Android, iOS | The server could not be reached. This could be due to either: The network being down. Firewall issues. The server undergoing high loads. **Note**: There is an exemption in the iOS localisation key. For this error, it is `client.error.connection`. | | `102` | `clientErrorInvalidResponse` | Android, iOS | The server response could not be understood by the Encap API. **Example**: This could be caused by internal server error, or a misconfigured reverse proxy. | | `105` | `clientErrorInvalidInputFormat` | Android, iOS | The given input does not comply with the policy proposed by the Encap server. | | `106` | `clientErrorNotActivated` | Android, iOS | The client has not yet been activated, or was deactivated. This means that the operation was not preceded by a successful activate call. | | `109` | `clientErrorUnexpected` | Android, iOS | An unexpected error occurred on the client. | | `110` | `clientErrorWrongState` | Android, iOS | The attempted operation is not allowed in this state. **Example**: The corresponding start operation needs to be performed before the finish operation. | | `111` | `clientErrorConfiguration` | Android, iOS | There is a configuration error. This means that the attempted operation is not possible to perform with the current configuration. **Example**: This could be caused by an incorrectly configured public key used for end-to-end encryption. | | `120` | `clientErrorConnectionTimeout` | Android, iOS | The request to the Encap server timed out. | | `121` | `clientErrorNoInternetConnection` | Android, iOS | There is no internet connection. | | `122` | `clientErrorSecureConnectionCheckFailed` | Android, iOS | The secure connection check performed by the client failed. | | `127` | `clientErrorInvalidAuthParameters` | iOS | The authentication parameters that were provided are invalid. | | `128` | `clientErrorAuthMethodUnavailable` | Android, iOS | The authentication method is not enrolled on device. | | `129` | `clientErrorAuthMethodNotAllowed` | Android, iOS | The authentication method is not activated on the registration or is not configured on the server. | | `130` | `clientErrorAuthenticationFailed` | iOS | Biometric authentication on the device has failed. | | `131` | `clientErrorAuthenticationAborted` | iOS | Biometric authentication on the device was cancelled. | | `132` | `clientErrorAuthDataInvalidated` | Android, iOS | The authentication data was invalidated. Biometrics have been added or removed. | | `133` | `clientErrorDowngradeDetected` | Android, iOS | The API is not supported because it has been downgraded. **Note**: To resolve the issue, you must either: Deactivate locally. Reinstall the app. | | `134` | `EncapClientErrorRegistrationDataInvalidated` | iOS | The registration data is missing due to a backup or restore. This means that a local deactivation has been performed. | | `135` | `clientErrorRegistrationDataTooOld` | Android, iOS | The registration data stored on the device was created with an outdated version of the Encap protocol. This means that the client SDK version is new enough, but the device has not communicated with the Encap server in a significant amount of time (three years before the introduction of the server version). **Note**: It is not possible to perform an authentication without reactivation. | | `136` | `clientErrorUnauthorized` | Android, iOS | The server could not find a key pair matching the provided public key hash. You must ensure that the public key is correctly configured. | | `150` | `clientErrorTokenPurposeNotSupported` | Android, iOS | The purpose for obtaining a token is not supported. | | `151` | `clientErrorInvalidToken` | Android, iOS | The provided Encap token is not valid, or it has expired. | | `152` | `clientErrorInvalidRecoveryParameters` | Android, iOS | One of the provided recovery parameters is not valid. | | `153` | `clientErrorRecoveryDataNotPresent` | Android, iOS | Recovery data is not present in the backup. This could be because: There are problems with backup/restore. Recovery has not been added. | | `160` | `clientErrorAppAttestNotSupportedInExtension` | iOS | App attestation is not supported from the extension in `REQUIRED` mode. An authentication is required to be able to use this operation. | | `161` | `clientErrorOperationNotAllowedInExtension` | iOS | The current operation is not allowed from an extension. | | `170` | `clientErrorCrypto` | Android | An internal crypto error occurred in the client. This could occur if the required crypto functionality is not available on the device. | | `171` | `clientErrorIntegrity` | Android | The integrity check of the mobile client data failed. **Example**: This could be caused by data that has been tampered with. | | `172` | `clientErrorStorage` | Android, iOS | An error occurred whilst reading/writing mobile client data. **Example**: This could be caused by limited storage capacity on the device. | | `174` | `clientErrorStorageUnavailable` | iOS | Storage is unavailable. Failed to read or write data. **Example**: This could be caused by the device being locked. | | `175` | `clientErrorStorageNeedSharedGroup` | iOS | Storage is unavailable. Failed to read or write data. **Note**: This happened because extension support is enabled, but the App Group is not available. | | `181` | `clientErrorKeyUserNotAuthenticated` | Android | The end-user was not authenticated with a biometric method strong enough to be used with the Android KeyStore. If possible, the end-user can attempt to recover by changing the preferred biometric method in the settings on the device. | | `182` | `clientErrorBiometricAuthentication` | Android | A general error code for biometric authentication. This error indicates that there is a low-level encryption/decryption error of the data, involving the cipher and key protected by the biometrics. **Example**: This could be caused by `javax.crypto.IllegalBlockSizeException` or `javax.crypto.BadPaddingException`. In this case, the data to be encrypted/decrypted is a random number named **biometric salt**. This is stored on file in **shared preferences**, and used in the authentication algorithm. | | `183` | `clientErrorUniqueDeviceIdInvalidAlgorithm` | Android | The algorithm for getting the unique device identifier is unsupported. | | `184` | `clientErrorUniqueDeviceIdAccessFailure` | Android | A problem occurred when getting the unique device identifier. | | `185` | `clientErrorClientDataInvalid` | Android, iOS | The provided mobile client data exceeds the 1024-byte size limit, or contains unsupported 4-byte UTF-8 characters such as emojis or certain other symbols. | | `1200` | `clientErrorAndroidBiometricPromptAuthenticationFailed` | Android | A biometric method is valid but not recognised. **Example**: This error may occur if the end-user pushes a non-registered finger on the fingerprint sensor. Normally, no action is needed from the app for this error code, as BiometricPrompt will handle the UI and let the end-user retry. | | `1201` | `clientErrorAndroidBiometricPromptAcquiredGood` | Android | The image acquired was good. | | `1202` | `clientErrorAndroidBiometricPromptAcquiredPartial` | Android | Only a partial biometric image was detected. During enrolment, the end-user should be informed with what needs to happen to resolve this problem. **Example**: For fingerprint, "_Press firmly on the sensor_". | | `1203` | `clientErrorAndroidBiometricPromptAcquiredInsufficient` | Android | The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor. | | `1204` | `clientErrorAndroidBiometricPromptAcquiredImagerDirty` | Android | The biometric image was too noisy due to suspected or detected dirt on the sensor. **Example**: This could be due to multiple `{clientErrorAndroidBiometricPromptAcquiredInsufficient}` errors, or after detection of dirt on the fingerprint sensor (across a single or multiple pixels). The end-user is expected to take action to clean the sensor when this is returned. | | `1205` | `clientErrorAndroidBiometricPromptAcquiredTooSlow` | Android | The biometric image was unreadable due to lack of motion. | | `1206` | `clientErrorAndroidBiometricPromptAcquiredTooFast` | Android | The biometric image was incomplete due to quick motion. **Example**: This could happen if the end-user moved during acquisition. The end-user should be asked to repeat the operation more slowly. | | `1207` | `clientErrorAndroidBiometricPromptUnexpectedHelpCode` | Android | The Android BiometricPrompt API returned an unexpected help code. | | `1211` | `clientErrorAndroidBiometricPromptErrorHwUnavailable` | Android | The hardware is unavailable. Try again later. | | `1212` | `clientErrorAndroidBiometricPromptErrorUnableToProcess` | Android | The sensor was unable to process the current image. | | `1213` | `clientErrorAndroidBiometricPromptErrorTimeout` | Android | The current request has been running too long. **Note**: This is intended to prevent programs from waiting for the biometric sensor indefinitely. The timeout is platform and sensor-specific, but is generally approximately 30 seconds. | | `1214` | `clientErrorAndroidBiometricPromptErrorNoSpace` | Android | The operation cannot be completed because there is not enough storage remaining to complete the operation. **Note**: This error state is returned for operations such as enrolment. | | `1215` | `clientErrorAndroidBiometricPromptErrorCanceled` | Android | The operation was cancelled because the biometric sensor is unavailable. **Example**: This could be caused by: The end-user being switched. The device being locked. Another pending operation preventing or disabling it. | | `1217` | `clientErrorAndroidBiometricPromptErrorLockout` | Android | The operation was cancelled because the API is locked out due to too many attempts. This occurs after 5 failed attempts, and lasts for 30 seconds. | | `1218` | `clientErrorAndroidBiometricPromptErrorVendor` | Android | Hardware vendors may extend this list if there are conditions that do not fall under one of the above categories. Vendors are responsible for providing error strings for these errors. These messages are typically reserved for internal operations such as enrolment, but may be used to express vendor errors not otherwise covered. Applications are expected to show the error message string if they happen, but are advised not to rely on the message ID since they will be device and vendor-specific. | | `1219` | `clientErrorAndroidBiometricPromptErrorLockoutPermanent` | Android | The operation was cancelled because `BIOMETRIC_ERROR_LOCKOUT` occurred too many times. Biometric authentication is disabled until the end-user unlocks with strong authentication such as: PIN. Pattern. Password. | | `1220` | `clientErrorAndroidBiometricPromptErrorUserCanceled` | Android | The end-user cancelled the operation. Upon receiving this, applications should use an alternative authentication method such as a password. The application should also provide the means to return to biometric authentication, such as with a **Use Biometric** button. | | `1221` | `clientErrorAndroidBiometricPromptErrorNoBiometrics` | Android | The end-user does not have any biometrics enrolled. | | `1222` | `clientErrorAndroidBiometricPromptErrorHwNotPresent` | Android | The device does not have a biometric sensor. | | `1223` | `clientErrorAndroidBiometricPromptErrorNegativeButton` | Android | The end-user pressed the negative button. **Note**: This is a placeholder that is currently only used by the support library. | | `1224` | `clientErrorAndroidBiometricPromptErrorNoDeviceCredential` | Android | The device does not have a PIN, pattern, or password set up. | | `1225` | `clientErrorAndroidBiometricPromptErrorSecurityUpdateRequired` | Android | A security vulnerability has been discovered. The sensor is unavailable until a security update has addressed this issue. | | `1233` | `clientErrorAndroidBiometricPromptErrorUnexpectedErrorCode` | Android | The Android BiometricPrompt API returned an unexpected error code. | ::: ## Server errors The table below lists all errors that are triggered from the Encap SCA server. We refer to these as **server errors**. :::CustomTable{tableName="Server error codes" columnWidths="10% 20% 15% 55%"} | Code | Error name | Applicable platforms | Description | | :-- | :-- | :-- | :-- | | `200` | `serverErrorIncorrectActivationCode` | Android, iOS | The server was unable to look up an activation session from the given activation code. | | `201` | `serverErrorUnexpected` | Android, iOS | An unexpected problem occurred on the server. | | `202` | `serverErrorNotRegistered` | Android, iOS | The registration ID (`registrationId`) cannot be found. | | `203` | `Mapped to serverErrorUnexpected` | iOS | The registration is not yet fully activated, as it has not been preceded by a successful activate call. | | `204` | `Mapped to serverErrorUnexpected` | iOS | The operation requires an authenticated session, but the session is not yet fully authenticated as it has not been preceded by a successful authenticate call. | | `205` | `Mapped to serverErrorUnexpected` | iOS | The operation has not yet been initiated. The register/identify call is missing. | | `208` | `serverErrorNoSession` | Android, iOS | There is no active session found for the request. | | `210` | `serverErrorInvalidSession` | Android, iOS | An operation was attempted on a session that is in an invalid state. You must perform another **start authentication** operation before retrying the **finish authentication** operation. | | `213` | `serverErrorIncorrectResponse` | Android, iOS | Activation failed on the server because either: The verification of the client response to the server activation challenge failed. Verification of hardware key signature failed. | | `214` | `serverErrorAuthenticationFailed` | Android, iOS | The response to the authentication challenge was incorrect. **Example**: This could be due to an incorrect PIN, which causes the authentication to fail. | | `219` | `serverErrorApplicationIdMismatch` | Android, iOS | The application ID sent by the client did not match the application ID expected by the server. | | `221` | `serverErrorServiceUnavailable` | Android, iOS | The server could not be reached, or it is having technical difficulties. | | `224` | `serverErrorLockedByAdmin` | Android, iOS | The registration was locked by the server for a reason. **Example**: This could be caused by the registration being locked by an admin or customer support. | | `226` | `serverErrorLocked` | Android, iOS | The registration is locked because either: The maximum number of authentication attempts was exceeded. The device verification failed. | | `230` | `serverErrorNoMatchingAuthMethod` | Android, iOS | Could not find an authentication method with the same or higher level as requested by the Encap server. | | `231` | `serverErrorIllegalAuthMethod` | Android, iOS | The client tried to activate with an authentication method not allowed by the server's configuration. **Example**: This could be caused by activating fingerprint when the server only allows `DEVICE` and `DEVICE:PIN` . | | `232` | `serverErrorIllegalAuthFactor` | Android, iOS | Tried to use single-factor authentication when two-factor authentication is required. | | `235` | `serverErrorAuthMethodNotAllowed` | Android, iOS | The specified authentication method is not allowed for this session. | | `236` | `serverErrorNoSessionForPurpose` | Android, iOS | A session exists with another purpose set than what is in the request from the client. **Example**: This could be caused by a new authentication session replacing the current authentication session. | | `237` | `serverErrorApplicationIdNotFound` | Android, iOS | The application ID does not exist. | | `238` | `serverErrorApiVersionTooOldForServer` | Android, iOS | The API version is too old for the server. | | `239` | `serverErrorApiVersionTooNewForServer` | Android, iOS | The API version precedes the server. | | `240` | `serverErrorApiVersionTooOldForAppConfig` | Android, iOS | The application configuration has specified the version as outdated. | | `241` | `serverErrorApiVersionBlacklisted` | Android, iOS | The application configuration has explicitly blocklisted (sometimes referred to as blacklisted) this version. | | `242` | `serverErrorEncapServerToServiceProviderError` | Android, iOS | Something has gone wrong with the communication between the server and the service provider. | | `243` | `serverErrorNotParsable` | Android, iOS | The internal request parameter cannot be parsed. | | `244` | `serverErrorMissingParameter` | Android, iOS | The internal request is missing a required input parameter. | | `245` | `serverErrorMalformedParameter` | Android, iOS | The internal request parameter is malformed. | | `246` | `serverErrorActivationFailed` | Android, iOS | The **start activation** operation failed, but the client tried to finish the activation anyway. | | `249` | `serverErrorClientRequestTimeOutOfSync` | Android, iOS | The request has an older timestamp than the previous request. **Note**: This means that either: The request was delayed on the way. The clock on the phone has been set back in time. The end-user needs to wait for the `CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD` (given in milliseconds), then try again. **Note**: For further details, see the Encap server manual. | | `250` | `serverErrorReactivationOnUnknownDevice` | Android, iOS | Reactivation must be performed on the same device as it was activated on. | | `254` | `serverErrorAuthTokenCreationFailed` | Android, iOS | Creation of the authentication token failed on the server side. | | `255` | `serverErrorAuthTokenValidationFailed` | Android, iOS | Validation of the authentication token failed on the server side. | | `256` | `serverErrorAuthTokenAlreadyUsed` | Android, iOS | The provided token has already been used during another operation and cannot be used again. | | `257` | `serverErrorRecoveryAlreadyUsed` | Android, iOS | Recovery has already been used. **Note**: Each recovery can be used only once. | | `258` | `serverErrorRecoveryDoesNotExist` | Android, iOS | Recovery secrets are missing or have never been created for a selected account. | | `259` | `serverErrorRecoveryDisabled` | Android, iOS | Recovery operations have been disabled for either the given registration or selected application configuration. | | `260` | `serverErrorRecoveryLocked` | Android, iOS | Recovery has been locked and cannot be used. | | `261` | `serverErrorInvalidAuthTokenPurpose` | Android, iOS | A token with the wrong purpose has been used to perform an operation. | | `262` | `serverErrorInvalidAuthLevelForTokenRequest` | Android, iOS | The token request requires two-factor authentication. | | `263` | `serverErrorMissingAuthMethod ` | Android, iOS | The authentication method required for the operation is missing. | | `270` | `serverErrorGeofencingBoundaryValidationFailed` | Android, iOS | The server evaluation of the country against the allowed regions failed. | | `271` | `serverErrorGeofencingClientFailure` | Android, iOS | The client failed to obtain a location, or the geocode lookup failed. | | `280` | `serverErrorAppAttestUnexpectedError` | iOS | An unexpected failure occurred whilst processing AppAttest data. Check the error message for more details. | | `281` | `serverErrorAppAttestTimeout` | iOS | A timeout occurred whilst performing an App Attest operation. | | `282` | `serverErrorAppAttestNotSupported` | iOS | The device does not support App Attest. | | `283` | `serverErrorAppAttestServerUnavailable` | iOS | The Apple App Attest server is unavailable. | | `285` | `serverErrorInvalidPublicKeyForApplicationId` | Android, iOS | There is no key pair for the public key. | | `286` | `serverErrorPlayIntegrityTimeout` | Android | The activation or authentication failed due to the client timing out when performing Play Integrity Attestation. | | `287` | `serverErrorPlayIntegrityApiFailure` | Android | The activation or authentication failed due to the client encountering an API failure whilst performing Play Integrity Attestation. | | `288` | `serverErrorPlayIntegrityPlayServicesOutOfDate` | Android | The activation or authentication failed due to the Google Play Services client being out of date or disabled when performing a Play Integrity attestation. | ::: ## Recoverable errors `isRecoverableError` indicates whether the error is recoverable or final in a finish operation: - It will return `true` if the error is recoverable. - It will return `false` if the error is not recoverable. ### Android The table below lists the recoverable errors for Android. :::CustomTable{tableName="Android recoverable error codes" columnWidths="25% 75%"} | Code | Error name | | :-- | :-- | | `105` | `clientErrorInvalidInputFormat` | | `214` | `serverErrorAuthenticationFailed` | | `1200` | `clientErrorAndroidBiometricPromptAuthenticationFailed` | | `1202` | `clientErrorAndroidBiometricPromptAcquiredPartial` | | `1203` | `clientErrorAndroidBiometricPromptAcquiredInsufficient` | | `1204` | `clientErrorAndroidBiometricPromptAcquiredImagerDirty` | | `1205` | `clientErrorAndroidBiometricPromptAcquiredTooSlow` | | `1206` | `clientErrorAndroidBiometricPromptAcquiredTooFast` | | `1207` | `clientErrorAndroidBiometricPromptUnexpectedHelpCode` | ::: ### iOS The table below lists the recoverable errors for iOS. :::CustomTable{tableName="iOS recoverable error codes" columnWidths="25% 75%"} | Code | Error name | | :-- | :-- | | `100` | `clientErrorOperationInProgress` | | `105` | `clientErrorInvalidInputFormat` | | `120` | `clientErrorConnectionTimeout` | | `121` | `clientErrorNoInternetConnection` | | `130` | `clientErrorAuthenticationFailed` | | `131` | `clientErrorAuthenticationAborted` | ::: ## iOS localisation key For all iOS errors, there is a localisation key. The localisation key is the error name prefixed with `client.error.` or `server.error.`. --- ## Device hash(Appendix) The device hash is a SHA256 hash of a universally unique identifier (UUID) that the SDK generates using Apple's [CFUUIDCreate](https://developer.apple.com/documentation/corefoundation/1542906-cfuuidcreate) function and stores in the end-user's iCloud Keychain. ## How does it work? The device hash is the same for all registrations in the same application, as the SDK only generates it when the UUID is missing. If you have different applications integrated with Encap, then each application generates its own unique UUID. This means that the device hashes will be different across those applications, even if you install them on the same mobile device. ### Example flow - If you install **App A** on your device, then device hash `X` is generated. - If you delete and reinstall **App A** on the same device, then device hash `X` is retained. - If you install **App B** on the same device, then device hash `Y` is generated. ## Device hash deletion The device hash is not deleted during deactivation, or if the app is uninstalled and installed again. A factory reset deletes the device hash if the mobile device is not restored from a backup. In this case, the SDK generates a new UUID the next time an activation is performed. ## Device hash in iCloud backups Although the SDK may send the device hash to the backend server through Protobuf during backup registration, it explicitly excludes it from the local recovery data. The device hash **is not** saved to the encrypted backup blob stored in the end-user's iCloud Keychain. If you restore a backup to a new iPhone, it will not contain the device hash of the original, backed-up iPhone. --- ## Error handling(Appendix) ## About error handling When an operation on the `EncapController` fails, the `.failure` case will contain the `ErrorResult`. The `ErrorResult` object contains important information that the app can use to determine how to continue the flow. It can also be used to help guide the end-user on how to resolve the issue. In a production app, logging the right error information when errors occur can play a crucial role in finding bugs. It can also assist with corner cases that would otherwise be difficult to find and solve without the log. ## How does error handling work? The `ErrorResult` object contains the following properties: :::CustomTable{columnWidths="25% 50% 25%"} | **Property** | **Description** | **Example** | | :-- | :-- | :-- | | `errorCode` | A unique error code that identifies the type of error. It is a value of the `EncapError` enum, which can be checked using a switch statement. | `106` **Note**: This corresponds to `clientErrorNotActivated`. | | `technicalDescription` | A technical description of the error. This can help you to determine what went wrong. | `The client has not yet been activated or was deactivated (not preceded by a successful activate call).` | | `remainingAttempts` | Indicates how remaining attempts the end-user has to perform an authentication. After this, a failure will result in their registration being locked by the Encap server. **Note**: This property is only set when an authentication fails. | `3` | | `isRecoverableError` | A boolean that indicates whether the error is final, or if it is possible to retry in a finish operation. | `true` | | `underlyingError` | An `NSError` object that is typically generated by the operating system. **Note**: It is only set when an underlying error is available. | `Error Domain=no.encap.error.connection Code=-2 "Invalid HTTP status code"` **Example**: This could be related to connection or storage errors with more detailed information. | ::: :::note Note For any server-related errors in production, the `technicalDescription` property will return the following: ``` Error description not available in production. ``` ::: ### Examples - An example of error handling: ```swift title="Example: Error handling" case .failure(let error): switch error.errorCode { case .serverErrorLockedByAdmin: message = "The registration was locked down by by admin / customer support" @unknown default: message = "An unexpected error has occurred" } } ``` - An example of getting the `underlyingError` from the `errorResult`: ```swift title="Example: Getting the underlying error" case .failure(let error): // Example of getting the underlyingError from the ErrorResult if let underlyingError = error.underlyingError { log(underlyingError) } } ``` :::tip Our recommendation We recommended that you log the `underlyingError` when present, as this provide useful insights into the cause of the error. ::: ## Recoverable errors Most Encap SCA operations are divided into a start and a finish call. Typically, if a finish call fails, then the app must restart the process with a new start call before attempting the finish call again. However, in some cases, the app can retry the finish call directly without having to do this. To determine whether this is possible, you can check the return value of the property `isRecoverableError`: - If `true`, then the app or end-user can retry the same finish call without restarting the flow. - If `false`, then the app must restart the process with a new start call before attempting the finish call again. :::info Example For example, the error `clientErrorInvalidInputFormat` allows the app to retry the same finish call without restarting the flow. ::: ### Limited retries Certain types of recoverable errors may only have a limited amount of retries, such as when an incorrect PIN is entered. In these cases, `isRecoverableError` will still return `true`, but the error object will include details about how many more retry attempts are allowed. For a full list of recoverable errors, see the [Recoverable errors](/docs/mobile-identity/encap/sdk-error-codes/#recoverable-errors) section on the SDK error codes page. ## Logging errors We recommend that you implement proper error logging procedures, so that you can obtain valuable information about errors when they occur. This information allows us to identify and resolve the issue faster when you report it to us. The most valuable details you can provide us are: - The error code (`errorCode`). - The technical description (`technicalDescription`). - The underlying error (`underlyingError`). - The Encap operation the error occurred in. - The version of the Encap SDK. --- ## Example project(Appendix) ## About the example project The Encap SCA SDK for iOS is available for download from our repository. It comes with a standalone example project to demonstrate the use of the API. The repository is gated, therefore you require login credentials to access it. ## Get started 1. Request your Nexus repository login credentials from us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. 2. Navigate to our repository and enter your Nexus repository login credentials. Browse for the correct version of the ZIP file in our repository, then download and unzip it: - Link for [MobileID customers](https://nexus.pub.encap.no/#browse/browse:MobileID-partner:com%2Fencapsecurity%2Fencap-ios-test-client). - Link for [Encap SCA customers](https://nexus.pub.encap.no/#browse/browse:encap-partner-repository:com%2Fencapsecurity%2Fencap%2Fencap-ios-test-client). 3. Run the project or the app. 4. Set the `serverURL`: - For MobileID customers, use `https://api.signicat.com/encore/encap`. - For Encap SCA customers, use the URL for your Encap SCA server. --- ## Appendices(Appendix) You can learn about frequently asked questions, corner cases and recommendations in our appendices. * [**Device hash**](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash): Learn about the device hash * [**Error handling**](/docs/mobile-identity/encap/sdk-ios/appendix/error-handling): Learn how to handle errors * [**Example project**](/docs/mobile-identity/encap/sdk-ios/appendix/example-project): Use our example project to quickly get started with the Encap iOS SDK * [**Security best practices**](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices): Learn how to manage sensitive data and ensure PSD2 compliance :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Security best practices(Appendix) To maintain compliance with PSD2 (Payment Services Directive 2) and ensure robust application security, it is important that you properly manage how sensitive data is handled in memory. On this page, you can learn about: - The different types of data handled by the SDK. - The classification of data handled by the SDK. - How you should manage data in your application's memory lifecycle. ## How does it work? When handling authentication and user verification, sensitive data is temporarily loaded into the mobile device's memory. To prevent this data from being exposed in the event of a memory dump or a device-level compromise, we recommend that you overwrite secrets as early as possible after use, so that they are completely erased from memory. ### Classification definitions To learn about the different data classifications, see the table below: | **Classification** | **Description** | | :-- | :-- | | `SECRET` | This data is highly sensitive.

You should overwrite it in memory immediately after it is no longer required. | | `NOT SECRET` | This data is not considered highly sensitive.

You do not need to overwrite it after use, although doing so is safe and acceptable. | ## Data classification and handling You can learn about the specific data types, their security classification, and the reasoning behind their memory management requirements in the tables below. ### User inputs and codes (API changes in this SDK version) :::CustomTable{columnWidths="20% 20% 60%"} | **Data type** | **Classification** | **Memory management** | | :-- | :-- | :-- | | PIN | `SECRET` | The end-user's PIN must not be stored anywhere. It must be deleted or overwritten with a random value as early as possible after it is sent to the controller and no longer needed. **Note**: The SDK now requires `NSMutableString` for PIN parameters. | | Activation code | `SECRET` | This is a one-time code that could potentially be copied and used as long as the session remains valid (typically a maximum of 5 minutes). It presents a **possession factor takeover risk** and is even higher risk than the PIN. It must be deleted or overwritten with a random value from memory immediately after the activation is triggered. **Note**: The SDK now requires `NSMutableString` for activation code parameters. | | Recovery code | `SECRET` | The recovery code is similar to a PIN in terms of its validity lifecycle. It must be deleted or overwritten with a random value as soon as the recovery process is successfully initiated or rejected. **Note**: The SDK now requires `NSMutableString` for recovery code parameters. | ::: ### User inputs and codes (best practices) :::CustomTable{columnWidths="20% 20% 60%"} | **Data type** | **Classification** | **Memory management** | | :-- | :-- | :-- | | Face scan data | `SECRET` | This data contains biometric information. While Encap/SSF includes replay prevention, face data could theoretically be copied and reused by another FaceTec customer if not properly erased. It should be deleted, or not persisting beyond its immediate use. **Note**: The SDK does not provide API-enforced zeroing for face scan data, so this is client-side guidance. | | Derived secrets | `SECRET` | All secrets derived from the above data must be handled with the same care as their source secrets. It should be deleted or overwritten with random values as early as possible after use. **Note**: For example, these could be cryptographic keys derived from PINs, activation codes, or encrypted values. | ::: ### Authorisation token :::CustomTable{columnWidths="20% 20% 60%"} | **Data type** | **Classification** | **Memory management** | | :-- | :-- | :-- | | Token ID | `NOT SECRET` | The token ID is a hash that is only valid for the specific application on the device during recovery operations. Because the authorisation token cannot be utilised outside of this specific context, it does not strictly need to be overwritten. | | Token Value | `SECRET` | The token value is secret and should be treated as a one-time credential, similar to an activation code. It must be deleted or overwritten it with a random value immediately after use, as it is only valid for a single operation. | ::: :::info Want to learn more? To learn how the authorisation token is used for recovery operations, see the iOS [Account recovery](/docs/mobile-identity/encap/sdk-ios/configure-features/account-recovery#token-authorisation) feature documentation. ::: ## Memory management in Swift When handling PINs, activation codes, and recovery codes in Swift, you should not store the values as `String` or `NSString` objects. This is because they are both immutable, which leaves the sensitive data vulnerable to memory dumping and analysis. :::note What does this mean? Once a `String` or `NSString` is created, its value cannot be modified or overwritten; it remains in memory until the runtime decides to clean them up. ::: This is why the SDK requires `NSMutableString` for PIN, activation code, and recovery code parameters; it enables you to make a best-effort attempt to overwrite the data with `setString("")` immediately after use. ### Memory erasure limitations Although `NSMutableString.setString("")` performs best-effort clearing of the string's content, Foundation does not guarantee that previous in-memory copies or underlying buffers are securely overwritten. :::note What does this mean? Sensitive data may persist in allocator caches, runtime copies, or other memory regions. ::: This risk is why the entire chain of your code through to the SDK must use `NSMutableString` rather than `String`, so that you minimise the number of immutable copies in memory. However, neither `setString("")` nor the SDK's internal zeroing should be considered a cryptographic guarantee of memory erasure. ## Migration paths If you are updating an existing integration to work with this version of the SDK, there are two approaches. These are presented as [Option A](#option-a-full-psd2-compliance) and [Option B](#option-b-lightweight-wrapper-for-fast-shipping) in the sections below. ### Option A: Full PSD2 compliance :::tip Our recommendation This is the option that we recommend. ::: For this option, you adopt `NSMutableString` as the native type for credentials throughout your own codebase. This means that wherever the end-user's PIN or recovery code is stored, passed between screens, or held in a view model, you should use `NSMutableString` instead of `String`. You must ensure that you zero the values after passing them to the SDK. :::CustomTable{columnWidths="30% 70%"} | **Topic** | **Description** | | :-- | :-- | | What this achieves | The credential has a single memory location from the moment the end-user enters it to the moment it is zeroed. This is genuine end-to-end PSD2 compliance for credential handling. | | Typical effort | The effort involved is moderate. The credential type change propagates through the UI layer, such as text field delegate, view model, and coordinator/flow logic. **Note**: It is a refactor, not a rewrite, but it involves several files. | ::: #### Example ```swift title="Full compliance: Storing and zero as NSMutableString" // Store as NSMutableString, not String var pinCode = NSMutableString() // Pass directly — SDK will zero it after use encapController.finishActivation(withAuthMethod: .pin(value: pinCode), ...) { result in // Optionally zero your own reference too pinCode.setString("") } ``` ### Option B: Lightweight wrapper for fast shipping For this option, you keep your existing `String` code unchanged and wrap the value at the point of calling the SDK. :::CustomTable{columnWidths="30% 70%"} | **Topic** | **Description** | | :-- | :-- | | What this achieves | The SDK call compiles and works correctly. The SDK still zeros its copy of the credential. This is the minimum change required to be binary-compatible with the new SDK version. | | Typical effort | The effort involved is minimal. **Note**: It is a one-line wrap. | | Considerations | The original `String` still exists in memory alongside the wrapped copy. The SDK can zero the `NSMutableString` buffer, but it cannot reach back and zero the `String` that the client created. From a strict PSD2 audit perspective, the credential is still lingering. This option is appropriate for teams that need to ship quickly and are willing to accept a follow-up ticket for the full migration. | ::: #### Example ```swift title="Lightweight wrapper: Convert at call site" // Existing code stays as-is let pin: String = self.pinField.text ?? "" // Wrap immediately before the SDK call encapController.finishActivation(withAuthMethod: .pin(value: NSMutableString(string: pin)), ...) ``` ### Option comparison For a comparison of the two migration path options, see the table below: :::CustomTable{columnWidths="30% 35% 35%"} | **Topic** | **Option A** | **Option B** | | :-- | :-- | :-- | | **PSD2 compliant** | Yes | Partially **Note**: Only the SDK layer is compliant. | | **Code changes** | Moderate (type propagation) | Minimal (one-line wrap) | | **Recommended for** | New integrations Compliance-critical apps | Fast shipping Bridge to full migration | | **SDK update compiles** | Yes | Yes | ::: ## Client-side pattern: best-effort clearing of NSMutableString Since the SDK requires `NSMutableString` for PIN and recovery code parameters, you should adopt this pattern in your client code. After passing the secret to the SDK, you must immediately perform best-effort clearing of your own reference using the `defer` statement. The `defer` block ensures the clearing attempt happens regardless of whether the API call succeeds or returns an error. :::note Note This is a best-effort approach, not a cryptographic guarantee. ::: ```swift title="Example: Client code should attempt to clear its copy of the secret" func handlePinActivation(pin: NSMutableString) { defer { // Best-effort clearing: attempt to overwrite the content pin.setString("") } // Pass the NSMutableString to the SDK encapController.finishActivation(withAuthMethod: .pin(value: pin), ...) { result in // Handle result } // defer block runs here, attempting to clear the string } ``` --- ## Authentication methods(Sdk-ios) Encap supports several different authentication methods. Not every authentication method can be used on every platform. Below you will find: - The supported authentication methods for iOS. - The names of the enum cases that you need in order to activate and authenticate with these methods. :::note Available authentication methods The number of authentication methods could be limited by: - The application configuration on the Encap server, identified by the `applicationId`. - The mobile device's hardware. - The mobile device's state. ::: The supported authentication method can be one of the following enum cases found in `AuthMethod`: - `.device` - `.pin(value: NSMutableString)` :::warning Do not store the end-user's PIN You should not store the end-user's PIN anywhere. Overwrite/clear it from memory as early as possible after use. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices) appendix. ::: - `.strongTouchID(prompt: String?)` - `.faceID` - `.serverSideFace(faceScanData: FaceScanData?)` :::warning Face scan requires additional configuration When using the `.serverSideFace(faceScanData: FaceScanData?)` method, you need to undertake additional steps to correctly configure and implement face authentication. To learn how to do this, see our [Face authentication](/docs/mobile-identity/encap/features/face-authentication/) feature documentation. ::: ## Biometric authentication methods You can find the biometric authentication methods available for iOS below: :::CustomTable{columnWidths="25% 75%"} | **Name** | **Description** | | :-- | :-- | | `strongTouchID` | Data is stored using the `kSecAccessControlBiometryCurrentSet` flag. The authentication method will be invalidated if fingers are added or removed in the Touch ID settings. This means that an error message is shown to the end-user next time they try to use the authentication method. It will be deactivated automatically and not possible to use before being activated again. The device passcode is not a fallback. | | `faceID` | Data is stored using the `kSecAccessControlBiometryCurrentSet` flag. The authentication method will be invalidated if the Face ID settings are changed. This means that an error message is shown to the end-user next time they try to use the authentication method. It will be deactivated automatically and not possible to use before being activated again. The device passcode is not a fallback. | ::: ### Useful information - These methods will only be visible in the available/allowed list of authentication methods if they are supported and enrolled on the device. - Touch ID and Face ID authentication are disabled system-wide after five consecutive unsuccessful attempts, even when the attempts span multiple evaluation calls. When this happens, the system requires the end-user to enter the passcode for the device to re-enable biometry. :::info Want to learn more ? To learn more, see the [Apple Developer Documentation](https://developer.apple.com/documentation/localauthentication/lapolicy/deviceownerauthenticationwithbiometrics). ::: - Touch ID (`strongTouchID`) and Face ID (`faceID`) are ideal to activate together with a `PIN`, so that they can be reactivated using the `addOrUpdate` method if activation data is invalidated. :::info Want to learn more? To learn more, see the [Add or update](/docs/mobile-identity/encap/sdk-ios/core-operations.mdx#add-or-update) section on the **Core operations** page. ::: ## Available/allowed authentication methods When initiating an activation or authentication, the server provides you with a set of available/allowed `AuthMethod` values to activate or authenticate with: - `StartActivationResult.authMethodsForActivation` - `StartAddOrUpdateResult.authMethodsToActivate` - `StartResult.authMethodsForAuthentication` If more than one method is available, then the developer or end-user may choose which method to use. ## Server configured authentication methods The SDK also returns a raw list of server-configured authentication methods during the initial activation and in `addOrUpdate` results: - `StartActivationResult.serverConfiguredAuthMethods` - `StartAddOrUpdateResult.serverConfiguredAuthMethodsToActivate` The format will be the same as the configuration on Encap Server, for example: `DEVICE:PIN`, `DEVICE:STRONG_TOUCH_ID`, `DEVICE:IOS_FACE_ID`. It will also contain authentication methods for other platforms, such as Android. --- ## Account recovery(3) :::info About this documentation This documentation only describes how to configure the SDK for our account recovery feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/account-recovery)   [**Encap**](/docs/mobile-identity/encap/features/account-recovery) ::: ## How does account recovery work? ### Recovery methods For iOS, recovery is currently supported with the following recovery methods: | **Name** | **Recovery method** | | :-- | :-- | | Recovery code | `.backupRecoveryCode` | | Face scan | `.backupServerSideFace` | #### Recovery code :::warning Do not store the end-user's recovery code You should not store the end-user's recovery code anywhere. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices) appendix. ::: A recovery code is code that is chosen and remembered by the end-user. - Backup-based recovery uses a secret code (`recoveryCode`). - It is associated with the recovery method `.backupRecoveryCode`. - Recovery of this type will be deleted after recovery has been performed. ```swift title="Example: Recovery method with recovery code" RecoveryMethod.backupRecoveryCode(_: NSMutableString) ``` #### Face scan Face scan data is obtained from a face scan of the end-user. This data contains the face scan and optionally, audit trail images. - Recovery with face scan uses face scan data (`faceScanData`). - It is associated with the recovery method `.backupServerSideFace`. - This type of recovery is kept after the recovery is performed, to avoid the need for another face scan. :::warning Important The recovery method `.backupServerSideFace` requires that the authentication method `AuthMethod.serverSideFace` is added to the registration, before adding recovery. ::: ```swift title="Example: Recovery method with face scan" RecoveryMethod.backupServerSideFace(faceScanData: FaceScanData) ``` ### Supported backup types - iCloud backup. - Encrypted and unencrypted computer-based backup on Mac or PC. :::info Want to learn more? For additional details, see Apple's support documentation on [Backup methods for iPhone, iPad and iPod touch](https://support.apple.com/en-gb/HT204136). ::: ### Prerequisites The end-user is required to have: - An Apple ID. - iCloud Keychain enabled on their mobile device. :::note Note iCloud Keychain is only required for iCloud backups. ::: ### Token authorisation When you are using our SDKs for account recovery, you need to provide a token to authorise the operation. - Authorisation tokens are issued by our server when performing certain SDK operations. - In these operations, you need to set what purpose you will use the token for. - The token is returned back to the app as a response. - This token is used to authorise the next account recovery operation after a successful activation or authentication. :::info What does this mean? For example, this makes it possible to implement a flow that both registers the end-user and sets up recovery for the registration, without an additional authentication. ::: #### Operations that require a token An authorisation token is required for the following recovery-related operations: - `addOrUpdateRecovery` - `deleteRecovery` #### Operations that can yield a token The server will issue an authorisation token for the following operations: - `finishActivation` - `finishAuthentication` - `finishAddOrUpdateRecovery` - `finishRecovery` - `finishDeleteRecovery` #### Token purpose To request the authorisation token, you must provide one of the following purposes in the finish call: - `TokenPurpose.addOrUpdateRecovery` - `TokenPurpose.deleteRecovery` :::note Note The default value is `TokenPurpose.none`. ::: ## Configure the SDK ### How to get a token The operations `addOrUpdateRecovery` and `deleteRecovery` require an `EncapToken`. 1. To request a token, you must set the `tokenPurpose` in one of the [supported finish calls](#operations-that-can-yield-a-token). - If adding or updating recovery, set `TokenPurpose.addOrUpdateRecovery`. - If deleting recovery, set `TokenPurpose.deleteRecovery`. ```swift title="Example: Request a token during activation" EncapController.shared.startActivation(withCode: activationCode) { startResult in switch startResult { case .success(let activationResponse): // Setting tokenPurpose = .addOrUpdateRecovery EncapController.shared.finishActivation(withAuthMethod: .faceID, tokenPurpose: .addOrUpdateRecovery) { finishResult in ... } case .failure(let error): // Error } } ``` 2. The token is returned with the usual operation response. To learn how to access it, see example below: ```swift title="Example: Access a token" EncapController.shared.finishActivation(withAuthMethod: .faceID, tokenPurpose: .addOrUpdateRecovery) { finishResult in switch finishResult { case .success(let finishActivationResponse): // Token will be available by accessing finishActivationResponse.encapToken case .failure(let error): // Error } }) ``` ### Recovery code The following describes how to add, perform and delete recovery using a recovery code. #### Add account recovery To add account recovery and connect it to the end-user's registration, you can perform the `addOrUpdateRecovery` operation. This operation requires a valid `EncapToken` and `EncapRecoveryParameter` for the type of recovery method that should be activated. ```swift title="Example: How to add account recovery with RecoveryMethod.backupRecoveryCode" EncapController.shared.startAddOrUpdateRecovery(withToken: encapToken) { startResult in switch startResult { case .success(let successResult): EncapController.shared.finishAddOrUpdateRecovery(withRecoveryMethod: .backupRecoveryCode(NSMutableString(string: "123456"))) { finishResult in switch finishResult { case .success(let finishAddOrUpdateRecoveryResult): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` #### Perform an account recovery To recover an end-user's registration, you can perform the `startRecovery` and `finishRecovery` operations. This works similarly in concept to the activation process, where you must select and enable a new authentication method. - You can only enable one authentication method for a single recovery. - To add more authentication methods, you can perform the `addOrUpdate` operation. ```swift title="Example: Perform an account recovery with RecoveryMethod.backupRecoveryCode" EncapController.shared.startRecovery { startResult in switch startResult { case .success(let startRecoveryResult): EncapController.shared.finishRecovery(withRecoveryMethod: .backupRecoveryCode(NSMutableString(string: "123456")), authMethodToActivate: .faceID) { finishResult in switch finishResult { case .success(let finishRecoveryResult): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` :::note What is the recovery code? The `recoveryCode` is a secret code that is provided by the end-user, and is only known by them. - The end-user chooses the recovery code, which is a parameter to the `finishAddOrUpdateRecovery()` operation. - The end-user must then provide the same recovery code as a parameter to the `finishRecovery()` operation. - The end-user's choice of authentication method to activate is also a parameter to the `finishRecovery()` operation. ::: #### Delete a recovery To remove an active recovery, you can perform the `deleteRecovery` operation. ```swift title="Example: Delete a recovery with RecoveryMethod.backupRecoveryCode" EncapController.shared.startDeleteRecovery(withToken: encapToken) { startResult in switch startResult { case .success(_): EncapController.shared.finishDeleteRecovery(withRecoveryMethod: .backupRecoveryCode(NSMutableString(string: ""))) { finishResult in switch finishResult { case .success(let finishDeleteRecovery): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` ### Face scan The following describes how to add, perform and delete recovery using face scan. #### Add account recovery To add account recovery and connect it to the end-user's registration, you can perform the `addOrUpdateRecovery` operation. This operation requires a valid `EncapToken` and `EncapRecoveryParameter` for the type of recovery method that should be activated. ```swift title="Example: How to add account recovery with RecoveryMethod.backupServerSideFace" EncapController.shared.startAddOrUpdateRecovery(withToken: encapToken) { startResult in switch startResult { case .success(let successResult): EncapController.shared.finishAddOrUpdateRecovery(withRecoveryMethod: .backupServerSideFace(faceScanData: nil)) { finishResult in switch finishResult { case .success(let finishAddOrUpdateRecoveryResult): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` :::note Note - The `RecoveryMethod.backupServerSideFace` takes a `faceScanData` containing the face scan data of the end-user. - No face scan data is needed when adding recovery using the `RecoveryMethod.backupServerSideFace`, as the existing face scan from `addOrUpdate` is used. - The end-user needs to perform a new face scan when they perform a recovery later on. ::: #### Perform an account recovery To recover an end-user's registration, you can perform the `startRecovery` and `finishRecovery` operations. This works similarly in concept to the activation process, where you must select and enable a new authentication method. - You can only enable one authentication method for a single recovery. - To add more authentication methods, you can perform the `addOrUpdate` operation. ```swift title="Example: Perform an account recovery with RecoveryMethod.backupServerSideFace" EncapController.shared.startRecovery { startResult in switch startResult { case .success(let startRecoveryResult): EncapController.shared.finishRecovery(withRecoveryMethod: .backupServerSideFace(faceScanData: faceScanData), authMethodToActivate: .faceID) { finishResult in switch finishResult { case .success(let finishRecoveryResult): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` :::note What is the face scan data? - The `` contains a face scan of the end-user, optionally with audit trail images. - The end-user's choice of authentication method to activate is a parameter to the `finishRecovery()` operation. ::: #### Delete a recovery To remove an active recovery, you can perform the `deleteRecovery` operation. ```swift title="Example: Delete a recovery with RecoveryMethod.backupServerSideFace" EncapController.shared.startDeleteRecovery(withToken: encapToken) { startResult in switch startResult { case .success(_): EncapController.shared.finishDeleteRecovery(withRecoveryMethod: .backupServerSideFace(faceScanData: FaceScanData)) { finishResult in switch finishResult { case .success(let finishDeleteRecovery): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` ## Additional operations These additional operations can help you to create app logic in scenarios where a backup or restore has occurred, so that you can show recovery instead of a normal registration. ### Check if account recovery is added To check whether account recovery is added on a device, you can use the following method: ```swift title="Example: Check if recovery is activated" isRecoveryActivated ``` ### Check if device has been restored from backup To check whether the end-user's device has been restored from backup and your app is ready to perform account recovery, you can use the following app flow: 1. Check that `isActivatedLocally` is returning `false`. 2. Check that `isRecoveryActivated` is returning `true` before performing an account recovery. ### Identify activated recovery method To identify what the activated recovery method is, you can use `activatedRecoveryMethods`. --- ## App attestation(3) :::info About this documentation This documentation only describes how to configure the SDK for our app attestation feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/app-attestation)   [**Encap**](/docs/mobile-identity/encap/features/app-attestation) ::: ## Supported operations Attestation can be performed during activation, recovery, or any kind of authentication. Since a call is made to Apple's servers, the following operations that support app attestation may incur a delay of a few seconds: - `FinishActivation` - `FinishAddOrUpdate` - `FinishAuthentication` - `FinishRecovery` ## How to configure App Attest To use our app attestation feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK No mobile SDK configuration is required. To use App Attest, you need to configure the application configuration. Once you have done this, the server will start requesting the SDK to attest the application. ### Configure the application configuration The process for configuring the application configuration varies depending on whether you are a MobileID customer or an Encap SCA customer. You can use the buttons below to learn how to configure the application configuration for the different products. * [**Configure MobileID**](/docs/mobile-identity/mobileid/features/app-attestation#configure-the-application-configuration): Learn how to configure the application configuration for app attestation * [**Configure Encap SCA**](/docs/mobile-identity/encap/features/app-attestation#configure-the-application-configuration): Learn how to configure the application configuration for app attestation ## How to test App Attest ### Performing a successful test 1. Configure the server with the following settings: ``` "ATTESTATION_IOS_APP_ATTEST_MODE": "REQUIRED" "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT": "DEVELOPMENT" ``` 2. Launch Xcode, then connect a physical device and run the project on it. 3. Upon testing, you should be able to perform activations (registrations/enrolments) and authentications successfully without encountering any errors. ### Performing a negative test 1. Configure the server with the following settings: ``` "ATTESTATION_IOS_APP_ATTEST_MODE": "REQUIRED" "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT": "DEVELOPMENT" ``` 2. Launch Xcode, then connect a simulator and run the project on it. 3. Upon testing, you will encounter an error when attempting to perform an activation (registration/enrolment): ``` Error Code: 282 - AppAttest Attestation failed because device does not support App Attest. ``` ## Error codes The table below illustrates error codes related to App Attest if the attestation mode is set to `REQUIRED`. If the attestation mode is set to `OFF` or `OPTIONAL`, then no new error codes are introduced. You can find the corresponding error descriptions in our [SDK error codes](/docs/mobile-identity/encap/sdk-error-codes.mdx#server-errors) documentation. :::CustomTable{columnWidths="25% 75%"} | **Error code** | **Error name** | | :-- | :-- | | 280 | `serverErrorAppAttestUnexpectedError` | | 281 | `serverErrorAppAttestTimeout` | | 282 | `serverErrorAppAttestNotSupported` | | 283 | `serverErrorAppAttestAppleServerUnavailable` | ::: :::tip Our recommendation Do not activate or authenticate multiple controllers concurrently if not required, as doing this might cause the attest operations to fail. ::: --- ## Certificate pinning(Configure-features) Our certificate pinning feature gives applications additional security, as it guarantees that the Encap SDK only communicates with a trusted Encap server. By authenticating the client-server connection, it reduces the risk of man-in-the-middle (MITM) attacks. :::note Are you a MobileID customer? This feature is specific for Encap SCA customers. If you are a MobileID customer, then please see the MobileID [Certificate pinning](/docs/mobile-identity/mobileid/features/certificate-pinning/) feature documentation. ::: ## How does certificate pinning work? 1. The Encap SDK has to be configured with the hashes of the public keys in the certificate chain sent from the server that is trusted. 2. The Encap SDK compares the server's certificate with the configured hashes of public keys (`publicKeyHashes`). 3. The client only allows communication with the server if the certificate and `publicKeyHashes` match. ## Calculate the certificate pin To calculate the certificate pin, you need to have the certificate. If you do not have the certificate, then you can get it by going to the URL in your web browser. Then, use your browser to download the certificate. ### PEM format If the certificate is in PEM format, then you can calculate the hash with OpenSSL as follows: ``` openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64 ``` ### DER format If the certificate is in DER format, then you can calculate the hash with OpenSSL as follows: ``` openssl x509 -in certificate.der -pubkey -noout -inform der | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64 ``` ## How to configure certificate pinning You can support TLS/SSL certificate pinning with Encap by setting `publicKeyHashes`, which is located in `EncapConfig`. This is an array of public key hashes. This property holds hashes of public keys in the certificate chain sent from the server to trust, in the format `/`. This is the same as Chrome's format, for example: ``` sha256/i0qJOVXOc4mzxbcTUS21+wjE4IeaBTBA+cWy88Q34UU=" ``` --- ## Client debug data(Configure-features) ## About client debug data Our client debug data feature can help in error or support situations where extra data is required from the client, in order to understand the state of the application during operations. :::tip Note Client debug data is not intended to be enabled at all times. ::: ## How to configure client debug data To enable the feature, you have to enable it in the application configuration. See `CLIENT_DEBUG_DATA_ENABLED_OS_TYPES` in our application configuration documentation for more details. Regardless of whether sending debug data is enabled on the server, the end-user can always turn off sending debug data in the `EncapConfig` in the app. They can do this by setting `allowDebugData` to `false`. This is set to `true` by default. In order for data to be sent, the feature has to be enabled both in the application configuration, and in the app's `EncapConfig`. For complete list of the data that is collected by this feature, see the [Client debug data](/docs/mobile-identity/encap/sdk-ios/publish-your-app/collected-data.mdx#client-debug-data) section in our **Collected data** appendix. --- ## Device groups(3) :::info About this documentation This documentation only describes how to configure the SDK for our device groups feature. To learn about the feature and the full set of implementation requirements, see the main [Device groups](/docs/mobile-identity/encap/features/device-groups) feature documentation. ::: ## How to implement device groups You do not need to configure any specific mobile SDK settings to use device groups. However, to experience the full benefit of dynamic activation, then the devices need to be upgraded to SDK version 3.22 or later. ### Dynamic activation on new devices When a new device running SDK version 3.22 or later is added to a device group which has activated face authentication, then the `DEVICE_SERVER_SIDE_FACE` authentication method is dynamically activated on that device. This allows immediate use of face authentication without requiring the end-user to reactivate it. ### How does dynamic activation work? The SDK automatically handles dynamic activation during standard operational flows, specifically during: - `authentication` - `addOrUpdateAuthMethod` - `addOrUpdateRecovery` During these operations, if the server indicates that the `DEVICE_SERVER_SIDE_FACE` authentication method is available for the device group, then the SDK automatically activates it locally. :::note Synchronised deactivation If an end-user deactivates the face authentication method on one device, it is deactivated and deleted for the entire device group. ::: --- ## Extension support ## About extension support With iOS extensions, you can extend functionality for your end-users beyond your app. Our extension support feature allows your end-users to authenticate outside of your app; you can make content available to them whilst they are interacting with other apps or parts of the mobile operating system. ## How to configure extension support ### Prepare the project Before extension support can be activated, you need to make some changes to the project. #### Main target 1. Open the project file, select the main target project, then click the **Signing & Capabilities** tab. 2. Click **+**, then add App Groups and Keychain Sharing. 3. In the Keychain Sharing section, add a new Keychain group. This must be exactly the same as the `BundleID`, for example `com.company.app`. 4. In the App Groups section, add a new App Group. This must be exactly the same as the `BundleID`, but preceded by the word 'group'. For example, `group.com.company.app`. #### Extension target 1. Open the project file, select the extension target project, then click the **Signing & Capabilities** tab. 2. It is important that the `BundleID` from the extension target follows the Apple structure, and does not contain more than one period after the main application's `BundleID`. For example, `com.company.app.extensionName`. 3. Click **+**, then add App Groups and Keychain Sharing. 4. In the Keychain Sharing section, add a new Keychain group. This must be exactly the same as the main target `BundleID`, for example `com.company.app` 5. In the App Groups section, add a new App Group. This must be exactly the same as the main target `BundleID`, but preceded by the word 'group'. For example, `group.com.company.app`. :::tip Add the same frameworks You have to add the same frameworks to the extension target as you have to the main app. For further information, see the [Frameworks required by the EncapSwiftAPI](/docs/mobile-identity/encap/sdk-ios/getting-started.mdx#frameworks-required-by-the-encapswiftapi) section on our iOS SDK **Getting started** page. ::: ### Enable extension support :::warning Important information After enabling `extensionSupport`, there is no way to rollback and disable it. To disable it, the end-user must be deactivated and forced to do a new registration. ::: To activate the extension support, you need to set the `extensionSupport` field of the configuration to `true`: ```swift EncapController.shared.config.extensionSupport = true ``` #### How is the registration data handled? - For new registrations, the data will be stored in the Shared Group and Shared Keychain when extension support is enabled. - For existing registrations, the data will be migrated on the next successful authentication. - If the registration has biometrics activated, then the data will only be migrated when the biometric authentication method is used to authenticate. :::tip Note Keychain Sharing and App Groups are only accessible by apps made by members of the same Apple development team. ::: ## Check whether extension support is activated You can use `isActivatedWithExtensionSupport` to check whether the registration is activated with extension support. To do this: ```swift EncapController.shared.isActivatedWithExtensionSupport() ``` ## Perform an authentication To authenticate, you should use the same authentication method as in the main app. For more information, see our [authentication methods](/docs/mobile-identity/encap/sdk-ios/authentication-methods.mdx) page. If `isActivatedLocally` is returning `false` from an extension, this means that either: - The end-user has not activated with `extensionSupport` enabled. - The end-user has not migrated yet. When `extensionSupport` is enabled, the app can check `isActivatedLocally` and `isActivatedWithExtensionSupport` to identify situations where a migration is required before using this feature. ## Error codes The table below illustrates error codes related to extension support. You can find the corresponding error descriptions in our [SDK error codes](/docs/mobile-identity/encap/sdk-error-codes.mdx#client-errors) documentation. :::CustomTable{columnWidths="25% 75%"} | **Error Code** | **Error name** | | :-- | :-- | | 160 | `clientErrorAppAttestNotSupportedInExtension` | | 161 | `clientErrorOperationNotAllowedInExtension` | | 175 | `clientErrorStorageNeedSharedGroup` | ::: --- ## Face authentication(3) :::info About this documentation This documentation only describes how to configure the SDK for our face authentication feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/face-authentication)   [**Encap**](/docs/mobile-identity/encap/features/face-authentication) ::: ## Configure the SDK To use face authentication, you need to incorporate the FaceTec SDKs. The FaceTec SDK is available for download from our repository. The repository is gated, therefore you require login credentials to access it. 1. Request your Nexus repository login credentials from us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. 2. Navigate to our repository, then enter your Nexus repository login credentials. 3. Download the FaceTec SDK. 4. Drag and drop the `FaceTecSDK.xcframework` file into your project. :::tip Note Ensure that you select the **Copy items if needed** checkbox. ::: 5. In your project settings, navigate to **Target > General**. Set the FaceTec framework to **Embed & Sign**. 6. Open the `Info.plist` file, then add the new entry **Privacy - Camera Usage Description**. ## How to implement face authentication :::warning Do not store the end-user's face scan data You should not store the end-user's face scan data anywhere. For more information, see the [Security best practices](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices) appendix. ::: ### Overview To implement face authentication, you must typically use the following flow: 1. Start the process for either **Add or update** or for **Authentication**. You will then receive a `serverSideFaceInit` object. 2. Initialise the FaceTec SDK with the authorisations received from the `serverSideFaceInit` object. 3. The end-user performs the FaceScan, which provides a `sessionResult`. 4. Provide the `FaceScanData` object with the `sessionResult`, then finish the **Add or update** or **Authentication**. For further details specific to the operation, see the relevant sub-chapters. ### Activation Activation will be supported in a future release. This means that currently, you must: 1. **Activate** with PIN and/or biometrics. 2. Use the **Add or update** operation to add face authentication. ### AddOrUpdate #### Start call For an example of `startAddOrUpdate`, click to expand the collapsible section: :::details Click to expand ```swift class ViewController: UIViewController { var encapController = EncapController.shared private func startAddOrUpdateOfAuthMethod(clientData: String?) { let startParam = StartAddOrUpdateParameter(selectedAuthMethod: .serverSideFace(faceScanData: nil)) self.encapController.startAddOrUpdate(startAddOrUpdateParameter: startParam, onCompletion: { result in switch result { case .success(let successResult): if let serverSideFaceInit = successResult.serverSideFaceInit { self.initializeFacetecSDK(serverSideFaceInitResult: serverSideFaceInit) } case .failure(let errorResult): self.handleError(errorResult, in: .stateStartAddOrUpdate) } }) } } extension ViewController: FaceTecFaceScanProcessorDelegate { func initializeFacetecSDK(serverSideFaceInitResult: EncapSwiftAPI.ServerSideFaceInitResult) { if let deviceKeyIdentifier = serverSideFaceInitResult.deviceKeyIdentifier, let encryptionKey = serverSideFaceInitResult.encryptionKey, let sessionToken = serverSideFaceInitResult.sessionToken, let productionKeyText = serverSideFaceInitResult.productionKeyText { FaceTec.sdk.initializeInProductionMode(productionKeyText: productionKeyText, deviceKeyIdentifier: deviceKeyIdentifier, faceScanEncryptionKey: encryptionKey, completion: { initializationSuccessful in if(initializationSuccessful) { let verificationVC = FaceTec.sdk.createSessionVC(faceScanProcessorDelegate: self, sessionToken: sessionToken) DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { self.present(verificationVC, animated: true, completion: nil) } } else { // Initialization of Facetec SDK failed } }) } else { // Something missing } } // MARK: FaceTec Delegate func processSessionWhileFaceTecSDKWaits(sessionResult: FaceTecSessionResult, faceScanResultCallback: FaceTecFaceScanResultCallback) { switch sessionResult.status { case .sessionCompletedSuccessfully: faceScanResultCallback.onFaceScanResultCancel() let faceScanData = FaceScanData(faceScanBase64: sessionResult.faceScanBase64 ?? "", auditTrailImageBase64: sessionResult.auditTrailCompressedBase64?.first ?? "", lowQualityAuditTrailImageBase64: sessionResult.lowQualityAuditTrailCompressedBase64?.first ?? "") self.handleFinishLogicForFacetec(faceScanData: faceScanData) case .userCancelled: faceScanResultCallback.onFaceScanResultCancel() default: faceScanResultCallback.onFaceScanResultCancel() self.showAlert(title: "Error", message: errorHandler(facetecSessionResult: sessionResult)) } } } ``` ::: #### Finish call For an example of `finishAddOrUpdate`, click to expand the collapsible section: :::details Click to expand ```swift private func handleFinishLogicForFacetec(faceScanData: FaceScanData?) { let toAuthenticate: AuthMethod = .pin(value: NSMutableString(string: "1111")) // You can also authenticate using other methods e.g. // let toAuthenticate: AuthMethod = .faceID // let toAuthenticate: AuthMethod = .strongTouchID(prompt: nil) self.finishAddOrUpdateOfAuthMethod(withAuthMethod: .serverSideFace(faceScanData: faceScanData),toAuthenticate: toAuthenticate) } func finishAddOrUpdateOfAuthMethod(withAuthMethod toActivate: AuthMethod, toAuthenticate: AuthMethod) { self.animate() self.activeController.finishAddOrUpdate(authMethodToActivate: toActivate, authMethodToAuthenticate: toAuthenticate,onCompletion: { result in self.stopAnimate() switch result { case .success(let finishAddOrUpdateResult): // Done case .failure(let errorResult): // Handle error } }) } ``` ::: ### Authentication To be able to conduct a face authentication, you must start the process using the REST API. To do this, start a new authentication, where the request has the `authentication_method` field defined with the value `DEVICE_SERVER_SIDE_FACE`. #### Start call For an example of `startAuthentication`, click to expand the collapsible section: :::details Click to expand ```swift class ViewController: UIViewController { var encapController = EncapController.shared private func startAuthentication(clientData: String?) { self.encapController.startAuthentication(clientOnly: false, onCompletion: { result in switch result { case .success(let successResult): if let serverSideFaceInit = successResult.serverSideFaceInit { self.initializeFacetecSDK(serverSideFaceInitResult: serverSideFaceInit) } case .failure(let errorResult): // handle Error } }) } } extension ViewController: FaceTecFaceScanProcessorDelegate { func initializeFacetecSDK(serverSideFaceInitResult: EncapSwiftAPI.ServerSideFaceInitResult) { if let deviceKeyIdentifier = serverSideFaceInitResult.deviceKeyIdentifier, let encryptionKey = serverSideFaceInitResult.encryptionKey, let sessionToken = serverSideFaceInitResult.sessionToken, let productionKeyText = serverSideFaceInitResult.productionKeyText { FaceTec.sdk.initializeInProductionMode(productionKeyText: productionKeyText, deviceKeyIdentifier: deviceKeyIdentifier, faceScanEncryptionKey: encryptionKey, completion: { initializationSuccessful in if(initializationSuccessful) { self.setCustomization() let verificationVC = FaceTec.sdk.createSessionVC(faceScanProcessorDelegate: self, sessionToken: sessionToken) DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { self.present(verificationVC, animated: true, completion: nil) } } else { // Initialization of Facetec SDK failed } }) } else { // Something missing } } // MARK: FaceTec Delegate func processSessionWhileFaceTecSDKWaits(sessionResult: FaceTecSessionResult, faceScanResultCallback: FaceTecFaceScanResultCallback) { switch sessionResult.status { case .sessionCompletedSuccessfully: faceScanResultCallback.onFaceScanResultCancel() let faceScanData = FaceScanData(faceScanBase64: sessionResult.faceScanBase64 ?? "", auditTrailImageBase64: sessionResult.auditTrailCompressedBase64?.first ?? "", lowQualityAuditTrailImageBase64: sessionResult.lowQualityAuditTrailCompressedBase64?.first ?? "") self.handleFinishLogicForFacetec(faceScanData: faceScanData) case .userCancelled: faceScanResultCallback.onFaceScanResultCancel() default: faceScanResultCallback.onFaceScanResultCancel() self.showAlert(title: "Error", message: errorHandler(facetecSessionResult: sessionResult)) } } } ``` ::: #### Finish call For an example of `finishAuthentication`, click to expand the collapsible section: :::details Click to expand ```swift private func handleFinishLogicForFacetec(faceScanData: FaceScanData?) { self.finishAuthentication(withAuthMethod: .serverSideFace(faceScanData: faceScanData)) } func finishAuthentication(with authMethod: AuthMethod, tokenPurpose: TokenPurpose = .none) { self.encapController.finishAuthentication(withAuthMethod: authMethod, tokenPurpose: tokenPurpose, onCompletion: { result in switch result { case .success(let finishAuthResult): // Done case .failure(let errorResult): // handle Error } }) } ``` ::: ## Error handling Errors relating to FaceScan are propagated as follows: 1. Using the FaceTec delegate in your class, you must have the function `processSessionWhileFaceTecSDKWaits(sessionResult: FaceTecSessionResult, faceScanResultCallback: FaceTecFaceScanResultCallback)`. 2. The callback of delegate of the process will be available in sessionResult (`FaceTecSessionResult`). 3. You can check the status, which will indicate whether the session was either: - Completed successfully. - The cause of the failure. **Example: Code sample for error handling** :::details Click to expand ```swift func processSessionWhileFaceTecSDKWaits(sessionResult: FaceTecSessionResult, faceScanResultCallback: FaceTecFaceScanResultCallback) { switch sessionResult.status { case .sessionCompletedSuccessfully: // Successfully case .userCancelled: faceScanResultCallback.onFaceScanResultCancel() // Dismiss FaceTec screen default: faceScanResultCallback.onFaceScanResultCancel() // Dismiss FaceTec screen self.showAlert(title: "Error", message: errorHandler(facetecSessionResult: sessionResult)) } } private func errorHandler(facetecSessionResult: FaceTecSessionResult) -> String { var subTitle = "" switch facetecSessionResult.status { case .sessionUnsuccessful: subTitle = "The Facetec Session was not performed successfully and a FaceMap was not generated." case .nonProductionModeKeyInvalid: subTitle = "Your license is invalid or network connectivity issues occur during a session" case .cameraPermissionDenied: subTitle = "Camera Permission Denied" case .contextSwitch: subTitle = "Session was canceled due to the app being terminated, put to sleep, an OS notification, or the appwas placed in the background" case .landscapeModeNotAllowed: subTitle = "Session was canceled because device is in landscape mode" case .reversePortraitNotAllowed: subTitle = "Session was canceled because device is in reverse portrait mode" case .timeout: subTitle = "Session was canceled because the user was unable to complete a Facetec Session in the defaultallotted time" case .lowMemory: subTitle = "Session was canceled due to memory pressure" case .nonProductionModeNetworkRequired: subTitle = "Session was canceled because your App is not in production and requires a network connection" case .gracePeriodExceeded: subTitle = "Session was canceled because your License needs to be validated again" case .encryptionKeyInvalid: subTitle = "Session was canceled because the developer-configured encryption key was not valid" case .missingGuidanceImages: subTitle = "Session was canceled because not all guidance images were configured" case .cameraInitializationIssue: subTitle = "Session was canceled because Facetec was unable to start the camera on this device" case .lockedOut: subTitle = "Session was canceled because the user was in a locked out state" case .unknownInternalError: subTitle = "Session was canceled because of an unknown and unexpected error" default: subTitle = "\(facetecSessionResult.status.rawValue)" } return subTitle } ``` ::: ## Localisation The FaceTecSDK includes language resource strings prefixed with `FaceTec_`. It supports the following languages: - Afrikaans (af) - Arabic (ar) - German (de) - Greek (el) - English (en) - Spanish (es) - French (fr) - Kazakh (kk) - Norwegian (nb) - Portuguese (pt-BR) - Russian (ru) For further details, see the `FaceTecSDK.zip` file. ## Branding and styling ### What elements can be customised? The FaceTec SDK allows you to customise various branding and styling elements, such as: - Interface - Colours - Fonts - Borders To learn more about what you can customise, see the If you want to know more about what you can customise see the [UX, Themes & Branding](https://dev.facetec.com/ui-customization) page in the FaceTec documentation. ### How to customise the configuration To make changes, you have to create a `FaceTecCustomization` object, where you define each field that you want to change. :::details Example: Facetec customisation configuration ```swift let blueLeft = UIColor.init(red: 97/255, green: 210/255, blue: 250/255, alpha: 1) let blueRight = UIColor.init(red: 28/255, green: 122, blue: 247/255, alpha: 1) let gradientCgColor: [CGColor] = [blueLeft.cgColor, blueRight.cgColor] let fontBody = UIFont.systemFont(ofSize: 16, weight: .regular) let customization = FaceTecCustomization() customization.overlayCustomization.brandingImage = UIImage(named: "brandLogo") customization.frameCustomization.borderColor = blueLeft let backgroundLayer = CAGradientLayer.init() backgroundLayer.colors = gradientCgColor backgroundLayer.locations = [0,1] backgroundLayer.startPoint = CGPoint.init(x: 0, y: 0.5) backgroundLayer.endPoint = CGPoint.init(x: 1, y: 0.5) customization.feedbackCustomization.backgroundColor = backgroundLayer customization.feedbackCustomization.textFont = fontBody customization.ovalCustomization.strokeColor = blueLeft customization.ovalCustomization.progressColor1 = blueLeft customization.ovalCustomization.progressColor2 = blueRight customization.guidanceCustomization.foregroundColor = blueLeft customization.guidanceCustomization.readyScreenTextBackgroundColor = blueLeft customization.guidanceCustomization.buttonFont = fontBody customization.guidanceCustomization.buttonBackgroundNormalColor = blueLeft customization.guidanceCustomization.readyScreenTextBackgroundColor = blueLeft customization.resultScreenCustomization.foregroundColor = blueRight customization.resultScreenCustomization.activityIndicatorColor = blueLeft.withAlphaComponent(0.8) customization.resultScreenCustomization.uploadProgressTrackColor = blueLeft.withAlphaComponent(0.8) customization.resultScreenCustomization.messageFont = fontBody FaceTec.sdk.setCustomization(customization) ``` ::: ### Different environmental conditions You can apply different settings based on environmental conditions, such as low-light or bright-light situations. To do this, you must set a unique configuration for each of the scenarios using the `FaceTecCustomization` object. - Default: ```swift title="Example: Default configuration" FaceTec.sdk.setCustomization(customization) // Default ``` - Low-light ```swift title="Example: Low-light configuration" FaceTec.sdk.setLowLightCustomization(customization) // low-light ``` - Bright-light ```swift title="Example: Bright-light configuration" FaceTec.sdk.setDynamicDimmingCustomization(customization) // bright-light ``` ## Multiple controller scenario For a multiple controller scenario, face authentication must be activated for each controller. --- ## Geofencing(3) ## About geofencing Our geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. By limiting the use of Encap SCA activations (registrations/enrolments) and authentications to certain regions​, you can reduce the chance of fraud. ## How does geofencing work? When geofencing is enabled, the client will send the country code of the location of the device to the server. The server will verify the location and limit the use of the device based on the configuration in your application configuration and what you have set as your allowed regions. ### Supported operations Geofencing is supported in activation (registration/enrolment) and authentication operations. :::CustomTable{minTableSize="800px"} | **Method/operation name** | **Mode parameter used to configure geofencing** | **Is geofencing result sent in `OPTIONAL` mode?** | | :-- | :-- | :-- | | `startActivation`, `finishActivation` | `GEOFENCING_ACTIVATION_MODE` | | | `startRecovery`, `finishRecovery` | `GEOFENCING_ACTIVATION_MODE` | | | `startAuthentication`, `finishAuthentication` | `GEOFENCING_AUTHENTICATION_MODE` | | | `startAddOrUpdate`, `finishAddOrUpdate` | `GEOFENCING_AUTHENTICATION_MODE` | | ::: :::tip Receiving the geofencing result The geofencing result is returned from the Encap server to you using the REST API. ::: ### Functionality Geofencing is configured in your application configuration, through the following mode parameters: - `GEOFENCING_ACTIVATION_MODE` - `GEOFENCING_AUTHENTICATION_MODE` The mode that geofencing is set to determines the functionality when the app calls the methods illustrated in the table above. #### For start methods The Encap server informs the client about the current geofencing mode. If geofencing is enabled (`OPTIONAL` or `REQUIRED`), then the external geocoder platform is called with location as a parameter. #### For finish methods If geofencing is enabled (`OPTIONAL` or `REQUIRED`), then the client will send a request to the server that includes the country code from the geocoder external service, or without a country code if the lookup was not successful. If there is no location on the device, then the client will wait until the timeout measured from the start method to complete. The timeout is configured on the server for location and geofencing. ## How to configure geofencing To use our geofencing feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK To configure the mobile SDK for geofencing: 1. In order for the device to get a valid location for the reverse geocode lookup, you need to add a value for `NSLocationWhenInUseUsageDescription` in the app's `Info.plist`. This is the message that will be presented to the end-user the first time the Encap API starts looking for a location. :::tip Change the location accuracy You can also change the location accuracy if desired. To do this, see [accuracy](/docs/mobile-identity/encap/sdk-ios/configure-features/location.mdx#accuracy) in our location feature documentation. ::: 2. The end-user must grant location permissions on their mobile device. ### Configure the application configuration The process for configuring the application configuration varies depending on whether you are a MobileID customer or an Encap SCA customer. You can use the buttons below to learn how to configure the application configuration for the different products. * [**Configure MobileID**](/docs/mobile-identity/mobileid/features/geofencing#configure-the-application-configuration): Learn how to configure the application configuration for geofencing * [**Configure Encap SCA**](/docs/mobile-identity/encap/features/geofencing#configure-the-application-configuration): Learn how to configure the application configuration for geofencing ## Error codes The table below illustrates error codes related to geofencing if the geofencing mode is set to `REQUIRED`. If the geofencing mode is set to `OFF` or `OPTIONAL`, then no new error codes are introduced. You can find the corresponding error descriptions in our [SDK error codes](/docs/mobile-identity/encap/sdk-error-codes.mdx#client-errors) documentation. :::CustomTable{columnWidths="25% 75%"} | **Error code** | **Error name** | | :-- | :-- | | 270 | `serverErrorGeofencingBoundaryValidationFailed` | | 271 | `serverErrorGeofencingClientFailure` | ::: --- ## Configure features(Configure-features) You can learn how to configure our features in the iOS SDK using the feature guides below: * [**Account recovery**](/docs/mobile-identity/encap/sdk-ios/configure-features/account-recovery): Allow your end-users to recover their registration without the need for reactivation * [**App attestation**](/docs/mobile-identity/encap/sdk-ios/configure-features/app-attestation): Strengthen your application's security by preventing third-party use of our APIs * [**Certificate pinning**](/docs/mobile-identity/encap/sdk-ios/configure-features/certificate-pinning): Use certificate pinning to validate the requests from the server * [**Client debug data**](/docs/mobile-identity/encap/sdk-ios/configure-features/client-debug-data): Pass data from the client to the server for debugging purposes * [**Device groups**](/docs/mobile-identity/encap/sdk-ios/configure-features/device-groups): Create groups of devices that can share a single server-side FaceMap across them * [**Extension support**](/docs/mobile-identity/encap/sdk-ios/configure-features/extension-support): Authenticate your end-users outside of your application * [**Face authentication**](/docs/mobile-identity/encap/sdk-ios/configure-features/face-authentication): Add server-side face authentication to your app * [**Geofencing**](/docs/mobile-identity/encap/sdk-ios/configure-features/geofencing): Reduce fraud by limiting the use of your app to certain regions * [**Location**](/docs/mobile-identity/encap/sdk-ios/configure-features/location): Collect the location of the device for each operation * [**Operation context**](/docs/mobile-identity/encap/sdk-ios/configure-features/operation-context): Send important information to your app, through our secure channel * [**Push notifications**](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications): Send push notifications using Apple Push Notification service (APNs) * [**Risk parameters**](/docs/mobile-identity/encap/sdk-ios/configure-features/risk-parameters): Collect risk attributes for each operation :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Location(Configure-features) ## About location Location is one of the risk parameters that can be sent to the server. ## How does location work? Once configured, location data will be included in all requests to the server. The following values are collected: - `latitude` - `longitude` - `accuracy` - `altitude` When location is enabled, the location manager is not started until one of the start calls has been invoked. The location manager is disabled as soon as the finish call is completed. The location manager remains disabled until the next start call is invoked. ## How to configure location To enable collection of location by the Encap SDK, you must check that `ENABLED_RISK_DATA` is set to `ALL`, or that it contains `Location` in the application configuration. ### Add usage description The usage description is the message that will be presented to the end-user the first time that the SDK starts looking for a location. To add this, set a value for`NSLocationWhenInUseUsageDescription` in the app's `Info.plist` file. ### Accuracy To set your desired accuracy, you can use `EncapConfig` `setLocationAccuracy`. The default value is `kCLLocationAccuracyHundredMeters`. To learn more, see [Core Location Constants](https://developer.apple.com/documentation/corelocation/cllocationaccuracy) in the Apple developer documentation. ### Permission By default, when location or geofencing is enabled, the SDK prompts for location permission if not done by the app in the following operations: - `startActivation` - `startAddOrUpdate` - `startAuthentication` - `startAddOrUpdateOfRecovery` - `startDeleteRecovery` - `startRecovery` The `locationEnabled` flag found on `EncapConfig` can be used to prevent the SDK from prompting for location permission during enrolment. You can re-enable location updates after the end-user has enrolled or after your app has requested location permission. :::warning Warning You should be aware of the configuration that is used for the `applicationId` before changing this, as disabling location updates when geofencing is set to `REQUIRED` mode may result in unintended behaviour. ::: --- ## Operation context(Configure-features) ## About operation context You can use the operation context to add context to the activation or authentication attempt. ## How does operation context work? - For activation (registration/enrolment) operations, the Encap server can return a post-operation context. - For authentication operations, the Encap server can return both a pre-operation context and a post-operation context. You can find the data in the respective result classes: - `EncapFinishActivationResult` - `EncapStartAuthenticationResult` - `EncapFinishAuthenticationResult` - `FinishActivationResult` - `StartAuthenticationResult` - `FinishAuthenticationResult` To get the full operation context, you can use the following properties on the result classes: :::CustomTable{columnWidths="25% 75%"} | **Property** | **Description** | | :-- | :-- | | `contextTitle`| Get the title of the context returned. | | `contextContent`| Get the data for the context. | | `contextMIME`| Get the MIME type of the data sent in context content. | ::: You can read more about operation context in our [MobileID feature documentation](/docs/mobile-identity/mobileid/features/operation-context.mdx). --- ## Push notifications(3) :::info About this documentation This documentation only describes how to configure the SDK for our push notifications feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation: [**MobileID**](/docs/mobile-identity/mobileid/features/push-notifications/)   [**Encap**](/docs/mobile-identity/encap/features/push-notifications/) ::: ## How do push notifications work? For iOS, we support the use of the Apple Push Notification service (APNs) to notify the end-user when an operation has started. ## Configure the SDK To add support for notifications to your application, in the `UIApplicationDelegate` method `didFinishLaunchingWithOptions`, you have to: 1. Create an instance of `EncapPush`. 2. Register for APNS notifications. ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { self.encapPush = EncapPush() UNUserNotificationCenter.current().delegate = self UNUserNotificationCenter.current().requestAuthorization(options: [.list, .banner]) { granted, error in } application.registerForRemoteNotifications() ... } ``` 3. When the registration succeeds, the `UIApplicationDelegate` method `didRegisterForRemoteNotificationsWithDeviceToken` will be invoked. 4. Set the `deviceToken` property on your `EncapPush` instance: ```swift func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { self.encapPush.deviceToken = deviceToken } ``` 5. For every new notification sent to the application, the `UNUserNotificationCenterDelegate` methods will be invoked: | **Method** | **Description** | | :-- | :-- | | `userNotificationCenter:willPresentNotification:withCompletionHandler:` | If the application is in the foreground, this method is called when a notification is about to be presented to the user.| | `userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:` | If the application is in the background and the user has responded to the notification by opening the application, this method is called. | 6. Notify the SDK by invoking `handleNotificationWithUserInfo` on your `EncapPush` instance: ```swift let purpose = self.encapPush.handleNotification(userInfo) ``` 7. When the SDK receives the notification, it will: 1. Interpret the notification. 2. Establish the type of operation it requests of your application. 3. Return what type of purpose the push has. 8. This allows your application to present the correct user interface to the end-user: ```swift if let purpose = self.encapPush.handleNotification(notification.request.content.userInfo) { switch purpose { case .authentication: print("A notification has arrived requesting the application to authenticate the user. Invoke startAuthentication and present your authentication user interface.") case .performRecovery: print("Account Recovery") } } else { print("This push is not from Encap") } ``` ## Customise the push message Encap sets the loc-key in the push payload so that you can customise the message in the push notification. To do this, you need to add the supported keys in the app's `Localizable.strings` resource file. You can use the following supported keys: - `notification.authenticate` - `notification.performRecoveryNotification` ```swift title="Example: Localizable.strings for authenticate" "notification.authenticate" = "New authorization request received"; ``` ## Customise the push payload You can add a custom string in the push payload from the server-side. The `customPushPayload` method can be used to parse the value. If no value is present, then nil will be returned. ```swift func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) { let customPushPayload = self.encapPush.customPushPayload(notification.request.content.userInfo) completionHandler([]) } func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) { let customPushPayload = self.encapPush.customPushPayload(response.notification.request.content.userInfo) completionHandler() } ``` ## Time-Sensitive notifications Time Sensitive notifications are notifications that can break through system controls such as **Notification Summary** and **Focus**. We recommend that you use them to ensure that the end-user can see the requests, even when in Focus mode. To add support for these push notifications: 1. Select your project in Xcode. 2. Select **Signing & Capabilities**, then add **Time Sensitive Notifications**. 3. In your application configuration, set `APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED` to `true`. --- ## Risk parameters(Configure-features) ## About risk parameters Risk parameters are sent to the Encap SCA server and then passed on to you to make risk assessment possible. ## How to configure risk parameters You can enable and disable the risk parameters in the application configuration, by configuring `ENABLED_RISK_DATA`. You can get the information about what risk parameters are sent to the server by calling `riskparameterServerConfig` in the `EncapController`. This will return an `EncapRiskParameterServerConfig` object. With the function `setRiskParameter` on the `EncapController`, you can set risk parameters. Only `EncapRiskParameter.jailbreakDetected` is available for the app to set currently. :::info Want to learn more? For a complete list of the data that is collected by this feature, see the [Optionally collected data](/docs/mobile-identity/encap/sdk-ios/publish-your-app/collected-data.mdx#optionally-collected-data) section in our **Collected data** appendix. ::: ### Rooting status There is no default value for `EncapRiskParameter.jailbreakDetected`, so if the app does not call this function, then the rooting status is not passed on to the server. The app is free to implement the rooting detection as desired; either by its own implementation, or with a third-party library such as Promon SHIELD®. ### Wi-Fi information (SSID and BSSID) The SDK can be configured to collect the SSID (network name) and BSSID (network hardware address) of the Wi-Fi network to which the device is connected. This information can be a valuable component in risk assessment. For example, this can identify whether the end-user is on a known, trusted network. To enable the collection of this data, the following two conditions must be met: :::warning Important If either of these requirements are not met, then the SSID and BSSID are not collected or sent to the server. ::: - **Developer configuration**: You must add the Access Wi-Fi Information Entitlement to your application's target in Xcode. Without this entitlement, the SDK cannot access any Wi-Fi information. - **End-user permission**: The end-user of the application must have granted location permissions for the app. Apple requires location services to be enabled for an app to retrieve Wi-Fi network details. --- ## Core operations(Sdk-ios) ## Introduction On this page, you can learn about the different core operations that you can make with the SDK. ## Activation ### Overview Activation is the first thing that your application will guide your end-user through when using Encap. This process creates a link between your end-user's device and the Encap authentication server. This will later be used to establish trust. To activate the end-user's device, your application will invoke three methods on the `EncapController` in succession. You must: 1. **Optional**: Retrieve settings from the Encap server, such as activation code length and type. 2. Register the end-user's device on Encap server. The Encap server will then pass information back which the API will use to establish trust. 3. Activate the registration, using a selected authentication method and the information that was passed back in the previous step. :::tip Note Following these steps, the registration can now be used to authenticate the end-user that created it. ::: ### How to implement #### Retrieve settings from Encap server (optional) To begin the process, you can invoke `loadConfig`. :::tip Note It will return a `LoadConfigResult` object with information about the activation code length and type, so that the app can present the right keyboard and UI to input with the `toUIKeyboardType` method. Although this call is optional, it can improve the end-user's experience. ::: #### Register the end-user's device on the Encap server 1. Run the `startActivation` operation. 2. If the `startActivation` operation is successful, then the `StartActivationResult` object is returned as the `successResult`. This contains `authMethodsForActivation`, which is a set of authentication methods (`AuthMethod`) available for this device. - The list of authentication methods is filtered so that only those configured for this `applicationId` and enabled on the device are returned. - If more than one method is available, your app may let the end-user choose what authentication method to use. - In the case of `AuthMethod.pin`, you can use the `pinCodeType`, `pinCodeLengthMin` and `pinCodeLengthMax` properties to determine how to present an input form to your end-user for their PIN entry. - Similar to the activation code, you can use `pinCodeType.toUIKeyboardType()` to obtain the type of keyboard that is best suited for entering a PIN of the type expected by the Encap server. - You can check whether the end-user's input conforms to the PIN policy using the `pinCodeType.isValidFor(string: "")` method. The SDK will also perform this check on the PIN when the app tries to perform the next step. #### Activate the registration Once the `startActivation` operation has been completed successfully, you can finish the process. To do this, run the `finishActivation` operation with the desired authentication method. :::tip Explore supported authentication methods For supported authentication methods and additional details, see the [Authentication methods](/docs/mobile-identity/encap/sdk-ios/authentication-methods.mdx) page in our Encap SDK developer documentation. ::: :::tip The device as an authentication method The device as an authentication method (`AuthMethod.device`) will always be activated when activating a two-factor authentication method, such as PIN, Touch ID or Face ID. ::: ```swift title="How to activate a registration with Face ID" EncapController.shared.startActivation(withCode: activationCode) { startResult in switch startResult { case .success(let activationResponse): EncapController.shared.finishActivation(withAuthMethod: .faceID) { finishResult in switch finishResult { case .success(let finishActivationResponse): // Success case .failure(let error): // Error } } case .failure(let error): // Error } } ``` :::tip Note `AuthMethod.device` will always be activated when activating a two-factor authentication method such as `pin`, `touchID` and `faceID`. ::: #### Check if activation data is present You can use `isActivatedLocally` to check if the activation data is present on the device. This method will return a boolean value. This can be useful to determine flows in the application, such as whether the application should proceed with the activation flow. :::tip Note The `isActivatedLocally` method will not perform any call to the Encap server to check the status of current activation. ::: ```swift title="Example: Check if the registration is activated locally" do { let isActivated = try EncapController.shared.isActivatedLocally().get() } catch { // Handle error, the operation has failed due to an unexpected error. } ``` #### Fetch the registrationId After a successful activation, the `registrationId` is stored on the controller. ```swift title="Example: Fetch the registrationId" EncapController.shared.registrationId ``` :::tip Note The `registrationId` is the same as the `deviceId` and `device_id` which is used in the REST APIs. ::: ## Authentication ### Overview Authentication is a process used to prove that the current end-user is the same as the one who performed the initial activation. To authenticate the end-user, your application will invoke two methods on the `EncapController` in succession. The process is as follows: 1. Identify who your end-user claims to be to the Encap server. 2. The Encap server sends a challenge to the client API and a response is calculated. 3. If the authentication succeeds, then the Encap server has indicated trust that you are interacting with the correct end-user. ### How to perform an authentication #### Start the authentication 1. To begin the process, you need to run the `startAuthentication` operation. :::note About the clientOnly parameter - `clientOnly` is a legacy concept and should never be set to `true`. It will be removed in a future release. - For all authentication sessions, you have to pass `false` in the `clientOnly` parameter. ::: 2. If the `startAuthentication` operation is successful, then the `StartAuthenticationResult` object is returned in the `.success` case. This object has the following properties: :::CustomTable{columnWidths="25% 75%"} | **Property name** | **Description** | | :-- | :-- | | `lastAttempt` | Contains a date which indicates the last time somebody tried to authenticate themselves as the identification's end-user. | | `totalAttemptsPIN` | The total amount of invalid authentication attempts for `EncapAuthMethodDevicePIN` permitted by the server before the end-user's account is locked down by the server. This is to prevent brute-force entry. **Note**: Locked accounts need to be unlocked by contacting the Encap server operator or by using the administration web services of the Encap server from the Encap service provider. | | `remainingAttemptsPIN` | The amount of remaining invalid authentication attempts for `EncapAuthMethodDevicePIN` that the end-user has left before their account is locked down by the server. | | `contextTitle` | A short topical or categorical description of the end-user's authentication context. | | `contextContent` | Data in a form indicated by `contextMIME`, that can be used by the service provider to add some context to the authentication attempt. For example, if the end-user needs to authenticate themselves to allow a payment transaction to proceed, you could use the operation context to provide useful information to the end-user about the transaction. **Note**: It could be plain text, a web page, a PDF document, an image, or any other kind of contextual information. | | `contextMIME` | The MIME type of the `contextContent`. | | `authenticationMethod` | Indicates the type of authentication method used. | | `pinCodeLengthMin` | The minimum PIN length. | | `pinCodeLengthMax` | The maximum PIN length. | | `pinCodeType` | The type of PIN, so that the correct keyboard type can be displayed to the end-user. | ::: #### Finish the authentication 1. Once the `startAuthentication` operation has been completed successfully, you can finish the process by running the `finishAuthentication` operation. - If a PIN was used for the authentication, then you should include this in the PIN authentication parameters. :::note Note You should not store the end-user's PIN anywhere else. ::: - If Touch ID was used for the authentication, then you should provide the `touchIdPrompt` value for the Touch ID popup UI. For example, this could be a context message that is sent from the server. 2. If the authentication operation is successful, then the `FinishAuthenticationResult` object is returned in the `.success` case. 3. Your app's UI can use this object to determine how to proceed after the authentication has been completed. - Similar to the `ActivateResult`, this result provides a `responseType` and `contextContent` property. ```swift title="Example: How to authenticate with Face ID" EncapController.shared.startAuthentication() { startResult in switch startResult { case .success(let startAuthResponse): EncapController.shared.finishAuthentication(withAuthMethod: .faceID) { finishResult in switch finishResult { case .success(let finishAuthResponse): // Success case .failure(let error): // Error } } case .failure(let error): // Error } }) ``` ## Add or update ### Overview The `addOrUpdate` operation enables you to: - Add (activate) another authentication method to an existing registration. - Update an existing authentication method. ### Example use case Your end-user wants add another authentication method to their existing registration. For example, they want to activate both the PIN and the Touch ID authentication methods. To do this, you could: 1. Activate the first authentication method (PIN) as described in the [Activation](#activation) section. 2. The end-user activates the second authentication method (Touch ID) from within your app using the **Add or Update** method. ### How to implement #### Add another authentication to an existing registration 1. Activate the PIN as described in the [Activation](#activation) section. 2. The end-user activates Touch ID in your app by calling `startAddOrUpdate`. 3. If the operation is successful, `finishAddOrUpdate` object is returned, similar to the result from a `StartAuthentication` operation. 4. Use the `allowedAuthMethodsToActivate` parameter from the response object to select which authentication method to add. 5. Once the start call has been successfully executed, call `finishAddOrUpdate` with the `AuthMethod` for the authentication method that you want to activate. For example, this could be `AuthMethod.strongTouchID`, and then authorise this operation with PIN. :::tip Find activation and authentication parameters To find the right activation parameters (`activationParameters`) and authentication parameters (`authenticationParameters`), see the [Authentication methods](/docs/mobile-identity/encap/sdk-ios/authentication-methods.mdx) page in our Encap SDK developer documentation. ::: 6. Upon a successful result, the new authentication method has now been activated and is ready to be used to authenticate the end-user. ##### About implementation - A single-factor authentication method can not be used to add a two-factor authentication method. - You need to configure on the server which two-factor authentication methods can be used to add other two-factor authentication methods. - When you activate a two-factor authentication method, Encap will always activate the device as well. - There are only a few use cases where activating only the device makes sense, such as with a pure authenticator app. ##### Other use cases Another common use case is to update the end-user's PIN. To do this, you must follow the same steps as indicated above, however, you set PIN instead of `StrongTouchID` for the `activationParameters` in the finish call. ```swift title= "Example: How to add Face ID when PIN is activated" EncapController.shared.startAddOrUpdate { startResult in switch startResult { case .success(let startAddOrUpdateResponse): EncapController.shared.finishAddOrUpdate(authMethodToActivate: .faceID, authMethodToAuthenticate: .pin(value: pincode)) { finishResult in switch finishResult { case .success(let finishAddOrUpdateResponse): // Success case .failure(let error) // Error } } case .failure(let error): // Error } } ``` ## Deactivate ### Overview The `EncapController` provides two different deactivation methods. - Deactivate the registration. This could be useful if: - Your end-user no longer wants to have an account in your app and wants their data deleted. - Deactivate a specified authentication method. You may require deactivation or reactivation if the end-user forgets the PIN from their first activation. The scenario will then be identical to that of a first time activation. ### How to implement #### Deactivate the registration Run the `deactivate` method to delete all registration data for the given registration, including all of the authentication methods. - If the `onlyLocally` parameter is set to `false`, then the registration is removed both from the Encap server and locally. - If the `onlyLocally` parameter is set to `true`, then the registration will only be removed locally. :::tip Our recommendation It is advised to always try to deactivate towards the server. If the server is down or an other abnormality prevents you from deactivating towards the server, you can perform a local deactivation as a fallback. ::: ```swift title="Example: How to deactivate the registration" EncapController.shared.deactivate(onlyLocally: false) { result in switch result { case .success: // Success case.failure(let error): // Error } } ``` #### Deactivate a specified authentication method 1. Run the `deactivate` method and pass the `authMethod` to deactivate a specific authentication method. The registration will stay intact. 2. The end-user performs a device authentication. 3. The specified authentication method (`authMethod`) is removed both from the Encap server and locally. :::tip Limitations The device as an authentication method (`AuthMethod.device`) is used for authentication towards the server, and cannot be deactivated by this method. ::: ```swift title="Example: How to deactivate Face ID" EncapController.shared.deactivate(authMethod: .faceID) { result in switch result { case .success: // Success case .failure(let error): // Error } }) ``` ## Cancel session ### Overview You can use the `cancelSession` operation to cancel the activation or authentication session on the server. For example, you could use this when the client has been notified of a new transaction, but the user rejects it by pressing the cancel button. ### How to implement 1. Run the `cancelSession` operation. 2. The current activation or authentication session will now be cancelled on the server. ```swift title="Example: How to cancel a session" EncapController.shared.cancelSession { cancelResult in switch cancelResult { case .success: // Success case .failure(let error): // Error } }) ``` --- ## Getting started(Sdk-ios) ## Prerequisites Before you can get started, you must first install the following software: - Apple Xcode from the [Apple developer documentation](https://developer.apple.com/xcode/). :::warning Minimum iOS version The minimum supported iOS version for the Encap SDK is **iOS 15**. ::: ### Cross-platform integration The Encap SDK (EncapSwiftAPI) is optimised for Swift, utilising Swift features such as: - Enums with associated values - Result type - Value types (structs) For cross-platform developers such as React Native users, be aware that the Encap SDK is not directly compatible with Objective-C due to these Swift-specific features. ### How to handle cross-platform projects To use EncapSwiftAPI in cross-platform projects: 1. Create a Swift wrapper around the SDK. 2. Expose the necessary functionality to Objective-C through this wrapper. :::tip Our recommendation To ensure a successful integration, we recommend that you have familiarity with Swift and Objective-C interoperability. To get assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Add the SDK to your application The Encap SDK is available for download from our repository. The repository is gated, therefore you require login credentials to access it. 1. Request your Nexus repository login credentials from us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. 2. Navigate to our repository and enter your Nexus repository login credentials. Browse for the correct version using the following links: - Link for [MobileID customers](https://nexus.pub.encap.no/#browse/browse:MobileID-partner:com%2Fencapsecurity%2Fencap-ios-swift-api). - Link for [Encap SCA customers](https://nexus.pub.encap.no/#browse/browse:encap-partner-repository:com%2Fencapsecurity%2Fencap%2Fencap-ios-swift-api). 3. Download `EncapSwiftAPI.xcframework`. ## Configure your project For optimal use of the API, you need to set up and configure your IDE and project's configuration . :::danger Risk of registration data loss The EncapSwiftAPI framework uses Apple's Keychain for persistence. If the application's App ID prefix is changed, then this data will no longer be available to the API. As a result, if an app changes its App ID prefix, then all upgrading clients must re-activate with Encap. For new developments the App ID prefix will typically be your TeamID. For older developments, the App ID prefix uses a 10 digit alphanumeric. ::: You have to link `EncapSwiftAPI.xcframework` with your application, and add any other required frameworks. To do this: 1. Drag and drop `EncapSwiftAPI.xcframework` into your project directory, ensuring that it is added to the target. 2. Under the **TARGETS** list, select your application. 3. Click on the **Build Phases** tab. 4. Under **Link Binary With Libraries**, click the **+** button to add the system frameworks that are required by the Encap SDK. :::note Embed and sign the EncapSwiftAPI If you are using Xcode 15, embed the Encap framework that was dragged in. To ensure this is configured correctly, you can: 1. Navigate to **Frameworks, Libraries, and Embedded Content** in Xcode. 2. In the **Embed** column, click on the field corresponding to your EncapSwiftAPI framework. 3. Select **Embed & Sign** from the dropdown menu. This step will enable privacy manifests to be picked up by Xcode's tooling. ::: ### Frameworks required by the EncapSwiftAPI The following system frameworks are required by the EncapSwiftAPI: - `Security` - `SystemConfiguration` - `CoreLocation` - `LocalAuthentication` - `WebKit` - `UserNotifications` To use the classes and methods in the Encap, you need to import the EncapSwiftAPI: ```swift ``` ## Create the controller The Encap client API is exposed through the `EncapController` object which handles the state of all operations. Operations using the `EncapController` take several operation-specific parameters and a `onCompletion` block containing the `Result`. Once an operation has been dispatched as a request to the controller, its handling is asynchronous to the thread that initiated the operation. This allows the UI thread to invoke operations and not be blocked as they're being handled. The result is then passed to your application that contains either a `.success` or `.failure` case: - If the `Result` contains a `.success` value, then the operation is successful. - If the `Result` contains a `.failure` value, then the error result object can be used to determine how your UI should proceed. You can use your completion block to update the user interface to reflect the result. For example: - When the operation completes successfully, you could proceed to the next step; marking the user as logged in. - When the operation fails, you could let the user try the operation again; optionally allowing the user to update the provided input. An `EncapController` only supports a single operation at a time. It does not support multiple parallel operations simultaneously. You can use the `shared` method to retrieve an instance of the `EncapController`. ```swift title="Example: Use the shared method to retrieve an instance of the EncapController" EncapController.shared.loadConfig { result in switch result { case .success(let loadConfigResult): // Success case .failure(let error): // Error } } ``` ### Multiple active registrations in one application From Encap version 3.11, `initWithName` was added. This means that the `EncapController` can now be initialised with a unique name in order to support multiple active registrations in one application. ```swift title="Example: Initialise EncapController with a unique name" let controller = EncapController(name: "registrationA") ``` :::note Note If the app only supports one registration, then `shared` controller can be used. ::: ## Configure the controller To configure the controller, you can use the `EncapConfig` class. The SDK sets default values for most of its configuration properties, however, you must set the Encap server's URL and the public key for end-to-end encryption. You must update the settings **before** making any calls to the `EncapController` object. Configurations are not persistent to disk; they are only stored in memory, and therefore need to be set for every new instance of the `EncapController`. The following properties can be configured: :::CustomTable{columnWidths="20% 70% 10%"} | **Properties** | **Description** | **Required** | | :-- | :-- | :-- | | `serverURL` | The URL of the Encap server. | | | `applicationId` | The identifier for your application configuration. This contains specific settings for your app. | | | `publicKey` | The public key used for end-to-end encrypted communication. This is Base64 [DER encoded](https://en.wikipedia.org/wiki/X.690#DER_encoding). To find out how to generate a valid Elliptic curve key pair, see the [Managing E2E using the REST API](/docs/mobile-identity/encap/server/manual/server-configuration/#managing-e2e-keys-using-the-rest-api) secction on the Encap **Server configuration** page. **Note**: Supports X25519 curve. | | | `connectionTimeOut` | The amount of time in seconds before the connection the Encap server times out. **Default value**: `20` seconds | | | `publicKeyHashes` | For details, see our [Certificate pinning](/docs/mobile-identity/encap/sdk-ios/configure-features/certificate-pinning.mdx) feature documentation. | | | `locationAccuracy` | The accuracy of the location. | | `kCLLocationAccuracy` `HundredMeters` | | `locationEnabled` | Configures whether the SDK should disable location updates. This config will only have an effect if Location or Geofencing feature is configured. **Default value**: `true` | | | `allowDebugData` | For details, see our [Client debug data](/docs/mobile-identity/encap/sdk-ios/configure-features/client-debug-data.mdx) feature documentation. **Default value**: `true` | | | `extensionSupport` | For details, see our [Extension support](/docs/mobile-identity/encap/sdk-ios/configure-features/extension-support.mdx) feature documentation. **Default value**: `false` | | ::: ```swift title="Example: How to set configuration properties" let config = EncapConfig(serverURL: "https://demo.encapsecurity.com/pt/", applicationId: "encapApiTest", publicKey: "someKey") EncapController.shared.config = config ``` :::note MobileID customers For MobileID customers, you must configure the following properties in the controller. This applies to both sandbox and production accounts: - `serverURL`: This is always `https://api.signicat.com/encore/encap`. - `applicationId`: To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. - `publicKey`: To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. ::: --- ## iOS SDK(Sdk-ios) The Encap client API hides the complexity of authenticating users and exposes a simple step-based API for your application to implement. ## How does it work? 1. Your application initiates an API call to begin the process. 2. Your application handles requests from the API by honouring and responding to them through additional API calls. ## Get started * [**Getting started**](/docs/mobile-identity/encap/sdk-ios/getting-started): Learn how to set up and get started with our iOS SDK * [**Core operations**](/docs/mobile-identity/encap/sdk-ios/core-operations): Read about the different core operations that you can do with our SDK * [**Authentication methods**](/docs/mobile-identity/encap/sdk-ios/authentication-methods): Read about the different authentication methods that we support * [**Configure features**](/docs/mobile-identity/encap/sdk-ios/configure-features/): Learn how to configure the different features that we offer in the mobile SDK * [**Publish your app**](/docs/mobile-identity/encap/sdk-ios/publish-your-app/): Find guidelines for a successful app release ## Support * [**Appendices**](/docs/mobile-identity/encap/sdk-ios/appendix/): Read about frequently asked questions, corner cases and recommendations * [**Error codes**](/docs/mobile-identity/encap/sdk-error-codes): See an overview of all errors that could occur when using our SDK :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Apple export compliance requirements ## About export compliance If your app uses, accesses, contains or incorporates encryption, Apple states that you must determine your export compliance requirements: > If your app uses, accesses, contains, implements, or incorporates encryption, and you intend to upload, test, and distribute > your app through the App Store, you'll need to determine your export compliance requirements in [App Store Connect](https://developer.apple.com/help/app-store-connect/manage-app-information/overview-of-export-compliance). You can read more about this in [Apple's developer documentation](https://developer.apple.com/help/app-store-connect/manage-app-information/overview-of-export-compliance). ## How does the Encap SDK use encryption? The Encap SDK only uses standard encryption algorithms. It does not use any proprietary encryption algorithms that are not accepted by international standards. We use encryption provided both from within the Apple operating system, and from our third-party dependency OpenSSL. ## Requirements for App Store Connect You should select the following option in App Store Connect: **Standard encryption algorithms instead of, or in addition to, using or accessing the encryption within Apple's operating system**. ### Additional requirements for France If your organisation operates in France, then Apple may require additional documentation to comply with local encryption export regulations. This is because apps distributed in France that use any kind of encryption, including standard algorithms such as those in the Encap SDK, require a **French encryption declaration form** (also known as *déclarations d'importation ou d'exportation de moyens de cryptologie*). If you do not provide the necessary documentation when submitting your app through App Store Connect, then your app's approval may be delayed. To learn more about these requirements and how to meet them, see the following pages in Apple's **App Store Connect Help** documentation: - [Export compliance documentation for encryption](https://developer.apple.com/help/app-store-connect/reference/app-information/export-compliance-documentation-for-encryption) - [Determine and upload app encryption documentation](https://developer.apple.com/help/app-store-connect/manage-app-information/determine-and-upload-app-encryption-documentation) :::danger Important If your app is not going to be available for distribution in France, then it is important to remove France from App Store Connect. To do this, go to **Monetization** > **Pricing and Availability** ::: --- ## Collected data(Publish-your-app) On this page, you can learn about all data that is collected by the iOS SDK and sent to the Encap server. ## Data disclosure requirements Following the introduction of Apple's App Store data disclosure requirements, Apple states that you must provide information about your app's privacy practices in App Store Connect: > You'll need to provide information about your app's privacy practices, including the practices of third-party partners whose code you integrate into your app, in App Store Connect. This information is required to submit new apps and app updates to the App Store. It is therefore important that you have a complete overview of the data being used by your app. :::info Want to learn more? You can read more about app privacy details in [Apple's developer documentation](https://developer.apple.com/app-store/app-privacy-details/). ::: ## Always collected data The values in this table are always collected and sent to the Encap server. This means that you cannot configure whether this data is collected or not. :::CustomTable{tableName="Always collected data" columnWidths="25% 50% 25%"} | **Data**| **Description** | **Example** | | :-- | :-- | :-- | | Encap SDK version | The Encap SDK version used by the application. | | | Device UUID | The unique identifier generated with Apple's [CFUUIDCreate](https://developer.apple.com/documentation/corefoundation/1542906-cfuuidcreate) function and stored in Keychain. You can read more about the device hash in our [Device hash](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash) appendix. | | Operating system name | The operating system name. | `iOS`, `iPadOS` | | Operating system type | The operating system type (`OperatingSystemType`) of the device. | `iOS` | | Device hash | The SHA256 hash of a unique identifier generated with Apple's [CFUUIDCreate](https://developer.apple.com/documentation/corefoundation/1542906-cfuuidcreate) function and stored in Keychain. To learn more about this, see our [Device hash](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash.mdx) appendix. | | ::: ## Optionally collected data The values in this table are optionally collected and sent to the Encap server. This means that you can configure whether the data is collected or not. To do this, you must enable the risk attribute. For further information, see `ENABLED_RISK_DATA` in the application configuration. :::CustomTable{tableName="Optionally collected data" columnWidths="25% 50% 25%"} | **Data** | **Description** | **Example** | | :-- | :-- | :-- | | Application hash | The SHA256 hash of the Bundle Identifier. The server can use this for detecting re-packaging. | | | Device model | The model name of the mobile device. | `iPad2,2`, `Nexus S` | | Operating system version | The operating system version of the mobile device. | `iOS 14.4` | | User-Agent | The HTTP User-Agent as reported from the mobile device application. | | Device manufacturer | The manufacturer of the mobile device. | `Apple` | | Secure screen lock | A Boolean value which indicates whether the mobile device has secure screen enabled. This indicates whether the end-user has enabled either biometric or passcode authentication for unlocking their mobile device. | | | Network Interfaces | An array containing the client network interfaces. This includes the type of the network and the IP address. The list can contain multiple interfaces if the end-user's mobile device is connected to more than one at the time of the transaction. | | | Root status | A Boolean value which indicates whether the mobile device has been jailbroken. | | | Battery level | The battery level of the mobile device, given as a percentage. | | | Power connection | A Boolean value which indicates whether the mobile device is being charged or is connected to a charger. | | | Location | The mobile device's location, including the latitude, longitude, altitude and accuracy. | | | Gravity | An array containing gravity force measurements with timestamp from the device's gravity sensor. | 
`[``  {``    "x": 0.7,``    "y": 3.3,``    "z": 0.9,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  },``  {``    "x": 0.8,``    "y": 3.2,``    "z": 0.8,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  }``]`
| | Magnetometer | An array containing magnetic field strength measurements with timestamp from the device's magnetometer sensor. | 
`[``  {``    "x": 1.0,``    "y": 2.0,``    "z": 3.0,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  },``  {``    "x": 1.1,``    "y": 2.1,``    "z": 3.1,``    "timestamp": "2025-08-22T10:28:25.548UTC"``  }``]`
| | Time zone | The current time zone setting of the device. | | | Locale | The current locale or language setting of the device. | | | SSID | Name of the Wi-Fi network that the device is connected to. **Note**: Requires the "Access Wi-Fi Information" entitlement and user location permission. | | | BSSID | MAC address of the connected Wi-Fi access point. **Note**: Requires the "Access Wi-Fi Information" entitlement and user location permission. | `00:14:22:01:23:45` | | VPN | A Boolean value which indicates whether the mobile device is connected to a VPN. | | | Proxy | A Boolean value which indicates whether the mobile device is connected to an HTTP/HTTPS Proxy. | | ::: ## Client debug data The values in this table are only collected and sent to the Encap server if both: - `allowDebugData` is enabled in the `EncapConfig`. - Client debug data is enabled in your application configuration. For further information, see `CLIENT_DEBUG_DATA_ENABLED_OS_TYPES` in the application configuration. :::CustomTable{tableName="Client debug data" columnWidths="25% 50% 25%"} | **Property** | **Description** | **Example** | | :-- | :-- | :-- | | `availableMemory` | The amount of memory left on the mobile device, given in MB. | `4613` | | `processId` | The process ID of the app performing the operation. See [processIdentifier](https://developer.apple.com/documentation/foundation/processinfo/1415929-processidentifier) in the Apple developer documentation for details. | `4247` | | `threadId` | The thread ID performing the operation. | `1172` | | `batterySaver` | A Boolean value that indicates whether **Low Power Mode** is enabled on the mobile device. | `false` | | `connectionType` | Indicates whether the operation is performed over a Wi-Fi or a cellular connection. This value can be either `wifi`, `cellular` or `nil` (unknown). | `wifi` | | `clientRequestTime` | The timestamp of the request as reported from the mobile device. Returned in pattern `HH:mm:ss.SSS`. | `10:36:26.160` | | `applicationState` | Indicates the application state. This value can be either `active`, `inactive`, or `background`. See [UIApplication.State](https://developer.apple.com/documentation/uikit/uiapplication/state) in the Apple developer documentation for details. | `active` | | `isIosAppOnMac` | A Boolean value that indicates whether the process is an iPhone or iPad app running on a Mac. **Note**: This only applies to iOS 14.0 and above. | `false` | | `isProtectedDataAvailable` | A Boolean value that indicates whether content protection is active on the device. See [isProtectedDataAvailable](https://developer.apple.com/documentation/uikit/uiapplication/1622925-isprotecteddataavailable) in the Apple developer documentation for details. | `true` | | `stateOfRegistration` | A string that indicates the current state of registration. This indicates how the data is currently stored for the given registration on the mobile device. This value can be either `notActivatedStorage`, `oldStorage`, `improvedStorage` or `extensionStorage`. | `improvedStorage` | ::: ## Client error reporting data The values in this table are collected when an unexpected error in the Encap SDK is reported. :::note Note Only errors occurring internally in the Encap SDK with the following client codes are reported: - `clientErrorUnexpected` - `clientErrorStorage` - `clientErrorStorageUnavailable` - `clientErrorStorageNeedSharedGroup` ::: :::CustomTable{tableName="Client error reporting data" columnWidths="25% 50% 25%"} | **Data** | **Description** | **Example** | | :-- | :-- | :-- | | `id` | An identifier derived from the registration ID of the Encap controller. | `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` | | `registrationId` | The registration ID of the Encap controller. | `6ca855c2-6ff8-4fb7-b053-3221c3048e86` | | `clientErrorCode` | The client error code associated with the error from the Encap SDK. | `172` | | `osErrorCode` | The underlying operating system error code associated with the client error. | `518` | | `stackTrace` | The stacktrace of the error from the Encap SDK. | `` | | `customMessage` | A detailed message of the error from the Encap SDK. | `Storage operation failed` | | `isPhoneLocked` | A Boolean value which indicates whether the mobile device is locked when the client error occurs. | `false` | | `operationState` | The controller operation state at the moment when the client error occurs. When the error occurs during a moment of transition between two operation states, the original state is considered. | `START_ACTIVATION` | | `applicationState` | The current app lifecycle state at the moment when the client error occurs. | `active` | | `clientTimestamp` | The timestamp of the moment when the client error occurs, as reported from the mobile device. This value represents the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. | `1772556557310` | | `deviceModel` | The model name of the mobile device. | `iPhone17,3` | | `deviceManufacturer` | The manufacturer of the mobile device. | `Apple` | | `deviceHash` | The SHA256 hash of a universally unique identifier (UUID) generated with Apple's `CFUUIDCreate` function. **Note**: You can read more about this in our [Device hash](/docs/mobile-identity/encap/sdk-ios/appendix/device-hash.mdx) appendix. | `SzQaI2zj+54ATPbbxFkTvetDMkJJ5FKhSGgaXEeRXJc=` | | `sdkVersion` | The Encap SDK version used by the application. | `3.22.0` | | `osVersion` | The operating system version of the mobile device. | `26.1` | ::: --- ## Publish your app(Publish-your-app) This page contains guidelines to help you deliver a successful, secure and compliant app release on the Apple App Store, whilst avoiding common pitfalls. * [**Apple export compliance requirements**](/docs/mobile-identity/encap/sdk-ios/publish-your-app/apple-export-compliance-requirements): Learn how to follow Apple export compliance requirements when using Encap SCA * [**Collected Data**](/docs/mobile-identity/encap/sdk-ios/publish-your-app/collected-data): Overview of the data collected about the device and application when using our iOS SDK --- ## APNs certificates and tokens ## Create an APNs provider certificate Push certificates for development and production . 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **App IDs**. 4. Create an App ID without a wildcard, if it does not already exist. :::tip Example `3L223ZX9Y3.com.armiento.test` ::: 5. Under **Enable Services**, enable **Push Notifications**. 6. Click on the App ID, then click the edit button. 7. Click **Create certificate** To start the wizard to generate a new Development Push SSL Certificate. 8. Download this certificate, then double-click on `aps_developer_identity.cer` to import it into your Keychain. 9. Launch **Keychain Access**, then on the left, click on **My Certificates**. :::tip Where to find Keychain Access This is located in **Application > Utilities**. You can also search for it with Spotlight. ::: 10. Expand **Apple Development Push Services**, then select **Apple Development Push Services** and your private key. 11. Right-click, then choose **Export 2 items...**. 12. Save as `.p12` and put in `encap/core/config` folder: ## Create an APNs provider authentication token 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **Keys**. 4. Select **Apple Push Notifications service (APNs)**, then enter a name for the token and click **Continue**. 5. Copy the `KeyID`, then download the token and store it in a secure place. :::warning Configure in the application configuration The steps above show you how to create an APNs provider authentication token. To configure it in the application configuration, you also need the `TeamID` and `BundleID` for the application. To obtain these, see the [How to find the TeamID](#how-to-find-the-teamid) and [How to find the BundleID](#how-to-find-the-bundleid) sections below. ::: ### How to find the TeamID The `TeamID` can be found in the membership details. To do this: 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Membership**. ### How to find the BundleID The `BundleID` can be found under **Identifiers**. To do this: 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **Identifiers**. 4. Select the application that you are configuring the APNs token for. ## Troubleshooting ### iOS Push notification not arriving The following steps will show you how to investigate why push notifications from the Encap server are not arriving at the client. #### Check whether you are using the correct application ID - This could happen if the iOS application is using the incorrect application ID. :::tip Example The iOS application `apiTest` is using application ID `encapApiTest`. ::: #### Check whether the certificate on the Encap server has expired. 1. Log in to the server, and locate the config folder: `.../encap/core/config` 2. List the Keystore containing the certificate to be investigated `-apns.p12`. :::tip Example 1. List `encapApiTest-apns.p12`. 2. Run `keytool -list -v -keystore encap/core/config/encapApiTest-apns.p12`. 3. Press enter when prompted for the password. 4. Locate the period of validity field. For example `Valid from: Tue Jan 02 10:08:49 UTC 2024 until: Fri Jan 31 10:08:48 UTC 2025`. ::: Diagram showing locating period of validity field --- ## Server ## About the Encap server The Encap server is an authentication server that can be used by a single trusted service provider. ## How does it work? It provides the service provider the ability to register and authenticate users securely using any of the device clients supported by the Encap server. ## Get started * [**Server manual**](/docs/mobile-identity/encap/server/manual): Learn how to install, set up and maintain an Encap server for a production environment * [**REST API guide**](/docs/mobile-identity/encap/server/rest-api-guide/): Learn about the Encap REST APIs * [**APNs certificates and tokens**](/docs/mobile-identity/encap/server/apns-certificates-and-tokens): Learn how to create APNs certificates and tokens * [**Scaling**](/docs/mobile-identity/encap/server/scaling): Discover guidelines for tuning common Encap use cases :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Application configuration ## Introduction An application configuration is a specific set of application attributes for a mobile application. Each application configured on the Encap server needs its own set of configuration attributes, and these determine how the application should work. ## How does it work? Application configurations are loaded from the Encap server database. If no application configuration is found in the Encap server database, then the server is started with a default application configuration which has `encap` as the app ID. Any value not specified in the application configuration will be set to the default value shown in the tables below. You can use the REST API to maintain application configurations at runtime. This means that you can add, modify and remove properties without the need to restart the server. ## Properties In the tables below, you can find an overview of all application configuration properties and their default values. ### Account recovery You can use the properties below to configure account recovery for your application. :::info Want to learn more? To learn more about this feature, see our [Account recovery](/docs/mobile-identity/encap/features/account-recovery.mdx) feature documentation. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `RECOVERY_ENABLED` | Determines whether your end-users can set up cloud-based recovery credentials for account recovery. | `TRUE`, `FALSE` | `FALSE` | | `RECOVERY_CODE_MIN_LENGTH` | The minimum number of characters that the recovery code can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `0` to `MAXINT`. | `6` | | `RECOVERY_CODE_MAX_LENGTH` | The maximum number of characters that the recovery code can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `0` to `MAXINT`. | `50` | | `RECOVERY_CODE_FORMAT` | The types of characters that can be used for the recovery code. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | `ALPHA`, `ALPHANUMERIC`, `ANY`, `NUMERIC` | `NUMERIC` | | `RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED` | The amount of failed recovery code attempts allowed for any client, before the recovery for the client is locked. | From `0` to `MAXINT`. | `3` | ::: ### App attestation The configuration is split into a set of properties for Play Integrity (Android) and App Attest (iOS). You can use the properties in the tables below to configure app attestation for your application, according to the mobile platform. :::info Want to learn more? To learn more about this feature, see our [App attestation](/docs/mobile-identity/encap/features/app-attestation.mdx) feature documentation. ::: #### Play Integrity (Android) Properties to configure app attestation for your Android application. :::warning Mandatory configurations If `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` is set to `REQUIRED` or `OPTIONAL`, then all Play Integrity configurations defined in the table below are required. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` | Determines whether Play Integrity attestation is performed, and how the request is handled. To learn more, see [How do attestation modes work?](#how-do-attestation-modes-work) | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_TIMEOUT` | The number of milliseconds before timeout for a request made to the Play Integrity service. After this time, the attestation request will time out. | From `1` to `MAXINT`. | | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY` | The Play Integrity attestation decryption key used to decrypt the integrity token. | Base64 string from Google Play Console. | | | `ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY` | The Play Integrity attestation verification key used to validate the integrity token. | Base64 string from Google Play Console. | | | `ATTESTATION_ANDROID_PACKAGE_NAME` | The APK package name. | String | | | `ATTESTATION_ANDROID_CERTIFICATE_DIGEST` | The APK certificate SHA-256 digest. | Base64 string | | ::: #### App Attest (iOS) Properties to configure app attestation for your iOS application. :::warning Mandatory configurations If `ATTESTATION_IOS_APP_ATTEST_MODE` is set to `REQUIRED` or `OPTIONAL`, then all App Attest configurations defined in the table below are required. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `ATTESTATION_IOS_APP_ATTEST_MODE` | Determines whether App Attest attestation is performed, and how the request is handled. To learn more, see [How do attestation modes work?](#how-do-attestation-modes-work) | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT` | Determines the environment where an iOS app that uses app attestation validates itself. | `PRODUCTION`, `DEVELOPMENT` | `PRODUCTION` | | `ATTESTATION_IOS_APP_ATTEST_TIMEOUT` | The number of milliseconds before timeout for a request made to the App Attest service. After this time, the attestation request will time out. | From `1` to `MAXINT` | `20000` | | `ATTESTATION_IOS_APP_ATTEST_APP_ID` | The iOS app ID, which is a concatenation of a 10-digit team identifier, a period, and the app's `CFBundleIdentifier` value. **Example**: `0123456789.com.company.myApp` | String | | ::: #### How do attestation modes work? The app attestation feature can be used in multiple modes. The modes are the same for Android and iOS, and are set using the following properties: - `ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE` (Android) - `ATTESTATION_IOS_APP_ATTEST_MODE` (iOS) :::CustomTable{columnWidths="25% 75%"} | **Attestation mode** | **Description** | | :-- | :-- | | `OFF` | The `OFF` mode means that attestation is not performed. By default, attestation is turned `OFF`. | | `OPTIONAL` | The `OPTIONAL` mode means that attestation is performed. If attestation fails, then the transaction will not fail, and a new attestation is performed on the next transaction. | | `REQUIRED` | The `REQUIRED` mode means that attestation is performed. If attestation fails, then the transaction will fail and the device is locked. The device must perform a successful attestation before it can be used for future transactions. Attestation is triggered on new activations (registrations/enrolments), or the first authentication if the activation (registration/enrolment) already exists. **Note**: Devices running versions of iOS older than iOS 14 will always fail if the mode is `REQUIRED`, due to requirements by the Apple App Attest API. | ::: ### Application behaviour You can use the properties below to configure the behaviour of your application. :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="1100px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY` | The lower limit for how guessable the activation code is. This is given as '1 in `x`', where this parameter represents `x`. If this value is below 1 in `x`, then the server prevents the new activation from starting. To learn more, see [How does guess probability work?](#how-does-guess-probability-work) | From `1000` to `MAXINT`. | `1000` | | `ACTIVATION_CODE_LENGTH` | The number of characters that the generated activation code will be. | From `4` to `MAXINT`. | `6` | | `ACTIVATION_CODE_TYPE` | The types of characters that can be used for the generated activation code. | `ANY`, `NUMERIC`, `ALPHA`, `ALPHANUMERIC` | `NUMERIC` | | `ALLOWED_AUTH_METHODS` | The allowed authentication methods, given as a comma-separated list. It is mandatory to have `DEVICE` as an allowed authentication method. For single-factor authentication, you need to explicitly specify it in the start authentication request. | `DEVICE`, `DEVICE:PIN`, `DEVICE:STRONG_TOUCH_ID`, `DEVICE:SAMSUNG_FINGERPRINT`, `DEVICE:ANDROID_FINGERPRINT`, `DEVICE:IOS_FACE_ID`, `DEVICE:ANDROID_BIOMETRIC_PROMPT`, `DEVICE:SERVER_SIDE_FACE` | `DEVICE`, `DEVICE:PIN` | | `ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE` | The allowed authentication methods when adding a new authentication method through our `AddOrUpdate` operation. Authentication methods are given as a comma-separated list. All authentication methods specified here must be present in the `ALLOWED_AUTH_METHODS` parameter. | `DEVICE`, `DEVICE:PIN`, `DEVICE:STRONG_TOUCH_ID`, `DEVICE:SAMSUNG_FINGERPRINT`, `DEVICE:ANDROID_FINGERPRINT`, `DEVICE:IOS_FACE_ID`, `DEVICE:ANDROID_BIOMETRIC_PROMPT`, `DEVICE:SERVER_SIDE_FACE` | `DEVICE:PIN` | | `AMOUNT_FAILURES_ALLOWED` | The amount of failed PIN authentications allowed for any client, before the end-user is locked out. | From `0` to `MAXINT`. | `3` | | `LOCK_SCOPE` | Determines the lock behaviour following failed authentication attempts. If `AUTH_METHOD`, then only the current authentication method will be locked. This allows the end-user to unlock it using another valid, unlocked method. If `DEVICE`, then the entire device will be locked, rendering all authentication methods unusable. In this case, you must unlock the device using the device admin REST API. | `AUTH_METHOD`, `DEVICE` | `AUTH_METHOD` | | `AUTHORIZATION_TOKEN_TIMEOUT` | The number of milliseconds that an authorisation token is valid for. | From `0` to `MAXINT`. | `300000` | | `CLIENT_ONLY_ALLOWED` | Determines whether the client is allowed to perform client-only activations (registrations/enrolments) and authentications. **Note**: A client-only operation is an operation that is not initiated as a request from you. | `TRUE`, `FALSE` | `TRUE` | | `ENCAP_API_BLACKLIST_ANDROID` | Determines which Android client SDK versions to blocklist (sometimes referred to as blacklist). Devices running blocklisted versions will be rejected/denied. | Comma-separated semantic version. **Example**: `"3.5.3, 3.6.8"` | | | `ENCAP_API_BLACKLIST_IOS` | Determines which iOS client SDK versions to blocklist (sometimes referred to as blacklist). Devices running blocklisted versions will be rejected/denied. | Comma-separated semantic version. **Example**: `"3.5.3, 3.6.8"` | | | `MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID` | The minimum Android client SDK version allowed. This can only be used to narrow down the allowed Android SDK versions (not extend). To learn more, see [How does minimum required Encap version work?](#how-does-minimum-required-encap-version-work) | Semantic version. **Example**: `"3.7.0"` | | | `MINIMUM_REQUIRED_ENCAP_API_VERSION_IOS` | The minimum iOS client SDK version allowed. This can only be used to narrow down the allowed iOS SDK versions (not extend). To learn more, see [How does minimum required Encap version work?](#how-does-minimum-required-encap-version-work) | Semantic version. **Example**: `"3.7.0"` | | | `PIN_CODE_LENGTH` | The minimum number of characters that the PIN can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `1` to `MAXINT`. | `4` | | `MAX_PIN_CODE_LENGTH` | The maximum number of characters that the PIN can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `1` to `MAXINT`. | `4` | | `PIN_CODE_TYPE` | The types of characters that can be used for the PIN. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | `ANY`, `NUMERIC`, `ALPHA`, `ALPHANUMERIC` | `NUMERIC` | | `SESSION_EXPIRY` | The number of milliseconds that a new client operation session remains valid for. After this time has elapsed, the session can no longer be used for any operations. | From `1` to `MAXINT`. | `300000` | | `MAXIMUM_SESSION_EXPIRY` | The maximum number of milliseconds that the `sessionExpiry` can be set to. | From `1` to `MAXINT`. | `300000` | ::: #### How does guess probability work? With the `ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY` property, you can set the lower limit for how guessable the activation code is. The Encap server calculates the guess probability based on the cardinality of: - The activation code type. - The activation code length. - The number of active activations. This means that in order to increase the number of concurrently active activations supported, you must either: - Increase the `ACTIVATION_CODE_LENGTH`. - Choose an `ACTIVATION_CODE_TYPE` with greater cardinality. **Example: Demonstration of allowed guess probability** :::details Click to expand With `ACTIVATION_CODE_LENGTH = 4` and `ACTIVATION_CODE_TYPE = NUMERIC`, there are 10,000 possible activation codes. This means that with one activation in progress, the chance of guessing the activation code is 1 in 10,000. With 10 concurrent activations in progress, the chance of guessing a valid activation code is reduced to 1 in 1,000: ``` 10000 ÷ 10 = 1000 ``` If an 11th activation session starts before any of the others finish, then it will fail the `ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY` check. This is because the chance is below 1 in 1,000: ``` 10000 ÷ 11 = 909.09 ``` ::: #### How does minimum required Encap version work? With the `MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID` and `MINIMUM_REQUIRED_ENCAP_API_VERSION_IOS` properties, you can set the minimum client SDK version allowed. The parameter for specifying the minimum required Encap version can only be used to narrow down the allowed SDK versions, not extend the range. **Example: Demonstration of minimum required Encap version** :::details Click to expand If the minimum supported client version on the server is version `"3.5.0"`, but you want to only allow version `"3.6.0"`, then you can achieve this by setting `"3.6.0"` as the value for this property. However, if set `"3.3.0"` as the value for this property, then it would have no effect. This is because it is below the minimum supported client version on the server. ::: ### Client debug data You can use the properties below to configure client debug data for your application. :::info Want to learn more? To learn more, see the [Client debug data](/docs/mobile-identity/encap/features/mobile-client-diagnostics.mdx#client-debug-data) section in our **Mobile client diagnostics** feature documentation. ::: :::CustomTable{columnWidths="25% 35% 20% 20%"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `CLIENT_DEBUG_DATA_ENABLED_OS_TYPES` | A comma-separated list of operating system types to enable client debug data for. It can be set for neither, one, or both platforms. | `IOS`, `ANDROID` | | ::: ### Client request validation :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="1000px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `CLIENT_REQUEST_TIME_VALIDATION_ENABLED` | Determines whether the timing of client requests are validated. If `true`, then requests which arrive at the server out of order can be blocked. **Note**: Out of order requests are rare, but can occur due to network and/or load balancing configuration issues. | `TRUE`, `FALSE` | `TRUE` | | `CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD` | The number of milliseconds for the client request time validation threshold. If the new request is within the set threshold of the previous request, then validation of the client request time is performed. **Note**: We recommend that this is equal to or higher than the load balancer wait timeout. | From `1` to `MAXINT`. | `300000` | ::: ### Event callback You can use the properties below to configure event callback for your application. :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `EVENT_CALLBACK_EVENTS` | Comma-separated list of events that trigger a REST callback to the configured service provider URL. For further control of when callback should be issued, you can filter events per API. **Note**: If an API is not specified, then the callback for the event will be sent regardless of API. | Allowed events `DEVICE_LOCKED`, `DEVICE_UNLOCKED`, `DEVICE_DEACTIVATED`, `DEVICE_ACTIVATION`, `DEVICE_AUTHENTICATION`, `DEVICE_ADD_OR_UPDATE_RECOVERY`, `DEVICE_PERFORM_RECOVERY`, `DEVICE_DELETE_RECOVERY` Allowed APIs: `DEVICE`, `REST` | | | `EVENT_CALLBACK_URL` | The URL at which you want to receive callback. **Note**: Callback needs to be configured for the application configuration in order to receive them at the URL. | | | ::: #### How does event callback work? With the `EVENT_CALLBACK_EVENTS` property, you can set a comma-separated list of events that you would like to trigger a REST callback to the configured service provider URL. For further control of when callback should be issued, you can filter events per API. If an API is not specified, then the callback for the event will be sent regardless of API. **Example: Format specification** ``` :[||<…>],:[||<…>] ``` **Example: Demonstration of event callback** :::details Click to expand **Example 1: Event callback** If you set: ``` DEVICE_LOCKED, DEVICE_DEACTIVATED:[REST] ``` Then callback for `DEVICE_LOCKED` is triggered regardless of which API initiated it, and callback for `DEVICE_DEACTIVATED` is triggered when you deactivate a device from the REST API. **Example 2: Event callback** If you set: ``` DEVICE_LOCKED, DEVICE_DEACTIVATED:[DEVICE] ``` Then callback for `DEVICE_LOCKED` is triggered regardless of which API initiated it, and callback for `DEVICE_DEACTIVATED` is triggered when the end-user initiates a deactivation request from the mobile app. ::: ### Face authentication You can use the property below to configure face authentication for your application. :::info Want to learn more? To learn more about this feature, see our [Face authentication](/docs/mobile-identity/encap/features/face-authentication.mdx) feature documentation. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `SERVER_SIDE_FACE_CREDENTIALS` | The client credentials used for requesting authentication tokens from the Signicat authentication server. **Note**: This value is obtained when creating an API client in the Signicat Dashboard. | `Base64(CLIENT_ID:CLIENT_SECRET)` | | ::: ### Geofencing You can use the properties below to configure geofencing for your application. The configuration is split into a set of properties for activation (registration/enrolment) and authentication, so that you can enforce different rules for the different operations. :::info Want to learn more? To learn more about this feature, see our [Geofencing](/docs/mobile-identity/encap/features/geofencing.mdx) feature documentation. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `GEOFENCING_ACTIVATION_MODE` | Determines whether geofencing is performed for activation (registration/enrolment), and how the request is handled. To learn more, see [How do geofencing modes work?](#how-do-geofencing-modes-work) | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `GEOFENCING_ACTIVATION_ALLOWED_CONTINENTS` | Comma-separated list of continents where activation (registration/enrolment) **is allowed**, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `GEOFENCING_ACTIVATION_ALLOWED_COUNTRIES` | Comma-separated list of countries where activation (registration/enrolment) **is allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. **Note**: These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_ACTIVATION_DENIED_COUNTRIES` | Comma-separated list of countries where activation (registration/enrolment) **is not allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. **Note**: These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_AUTHENTICATION_MODE` | Determines whether geofencing is performed for authentication, and how the request is handled. To learn more, see [How do geofencing modes work?](#how-do-geofencing-modes-work) | `OFF`, `OPTIONAL`, `REQUIRED` | `OFF` | | `GEOFENCING_AUTHENTICATION_ALLOWED_CONTINENTS` | Comma-separated list of continents where authentication **is allowed**, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `GEOFENCING_AUTHENTICATION_ALLOWED_COUNTRIES` | Comma-separated list of countries where authentication **is allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. **Note**: These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_AUTHENTICATION_DENIED_COUNTRIES` | Comma-separated list of countries where authentication **is not allowed**, in an ISO 3166-1 alpha-2 two-letter country code format. **Note**: These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `GEOFENCING_TIMEOUT` | The maximum time (given in milliseconds) to wait for the location lookup and reverse geocoding to complete on the client. The timing starts when the client calls the finish operation. If the timeout is exceeded, then the client will continue without a country. | From `0` to `MAXINT`. | `10000` | ::: #### How do geofencing modes work? The app attestation feature can be used in multiple modes. The modes are the same for activation and authentication operations, and are set using the following properties: - `GEOFENCING_ACTIVATION_MODE` (activation/registration/enrolment operations) - `GEOFENCING_AUTHENTICATION_MODE` (authentication operations) :::CustomTable{columnWidths="25% 75%"} | **Attestation mode** | **Description** | | :-- | :-- | | `OFF` | The `OFF` mode means that a device location check is not performed. | | `OPTIONAL` | The `OPTIONAL` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will still be performed. It is up to you what action is taken on the result. | | `REQUIRED` | The `REQUIRED` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will fail. | ::: ### Hardware-protected keys You can use the properties below to configure hardware-protected keys for your application. :::info Want to learn more? To learn more, see our [Hardware-protected keys](/docs/mobile-identity/encap/features/hardware-protected-keys) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `HWKEY_VALIDATION_STRATEGY` | Determines what to do with devices after they fail signature validation based on the hardware-protected keys. `REQUIRED`: Activations and authentications fail if hardware key validation fails. New in v3.22. `REQUIRED_IF_SUPPORTED` (previously `SUPPORTED` in v3.21): Activations and authentications are rejected only when the client provides a public key whose signature check fails. `OPTIONAL` (previously `RISK_PARAMS` in v3.21): Operations never fail because of hardware key validation; the result of the signature check is available as a risk parameter only. | `REQUIRED`, `REQUIRED_IF_SUPPORTED`, `OPTIONAL` | `REQUIRED_IF_SUPPORTED` | ::: ### Push notifications You can use the properties below to configure push notifications for your application. :::info Want to learn more? To learn more, see our [Push notifications](/docs/mobile-identity/encap/features/push-notifications/) feature documentation. ::: :::CustomTable{columnWidths="25% 35% 20% 20%" minTableSize="950px"} | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `APN_CONFIG` | The APN server configuration that defines where to reach (APNs). | `PRODUCTION`, `SANDBOX` | `PRODUCTION` | | `APN_EXPIRY` | The number of milliseconds that APNs will try to deliver the message for. If not delivered within this time, then the message is discarded. **Note**: APNS will attempt to deliver the message at least once, regardless of the set expiration time. | From `0` to `MAXINT`. | `0` | | `APNS_BUNDLE_ID` | Apple's bundle ID for the application. This is used as a topic on the push message sent to APNs, and is required when using APNs tokens (`APNS_TOKEN`). | String | | | `APNS_NOTIFICATION_SOUND_ENABLED` | Determines whether a notification sound is played on iOS devices when the device receives a push message. If `true`, then the default sound on the device is played when a push is received. If `false` or null, then no sound is played. **Note**: This only applies to iOS devices. For Android devices, the app determines whether a notification sound is played. | `TRUE`, `FALSE` | `FALSE` | | `APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED` | Determines whether the interruption level for push messages to iOS devices is set to 'Time-Sensitive'. If `true`, then notifications are given a higher-priority and end-users are notified even when in 'Focus' mode. If `false`, then the default interruption level 'Active' is assumed by the device. | `TRUE`, `FALSE` | `FALSE` | | `NATIVE_PUSH_ENABLED` | Enables the server to send push messages with Firebase Cloud Messaging (FCM) and Apple Push Notification service (APNs). | `TRUE`, `FALSE` | `FALSE` | | `FIREBASE_SERVICE_ACCOUNT` | The contents of the `serviceAccount.json` file (credentials file), for your Firebase Cloud Messaging (FCM) project. **Note**: This has to be supplied to us Base64-encoded. | String | `null` | | `FIREBASE_TIME_TO_LIVE` | The maximum lifespan of the message in milliseconds, for Firebase Cloud Messaging (FCM). The default value `0` means to deliver the message 'now or never'. FCM guarantees best effort for messages with this lifespan. | From `0` to `MAXINT`. | `0` | | `URL_SCHEME` | For Android only. The scheme part of a URL, which is generated for push methods that require a URL. **Note**: This is the URL scheme that the client is configured to be activated with. | A valid URL scheme | `encap` | ::: ### Risk data You can use the property below to configure risk data for your application. :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `ENABLED_RISK_DATA` | Determines which risk data to collect. This must be supplied as a comma-separated list If `ALL`, then all available risk data is stored. If null, then storage of risk data is disabled. **Note**: To learn more, see the REST API documentation. | `ALL`, `SystemVersion`, `IsRootAvailable`, `IsDebuggerConnected`, `IsDebuggable`, `IsDebugEnabled`, `IsEmulator`, `InputMethod`, `Fingerprint`, `UserAgent`, `SignerHashes`, `Location`, `NetworkInterfaces`, `IsSecureScreenLockEnabled`, `SeverClientIp`, `OperatingSystemType`, `ApplicationHash`, `DeviceHash`, `DeviceManufacturer`, `DeviceModel`, `HwKeyClientStatus`, `HwKeyServerResult`, `BatteryLevel`, `IsPowerConnected` | | ::: --- ## Audit log configuration ## Introduction :::danger Do not turn off audit logging Do not turn off all audit logging. Even if you do not have a compliance need for this data, it is highly useful when analysing any issues. We are not able to provide full support without audit logging. We highly recommend at least keeping 14 days of audit logging for support purposes. ::: There are two sets of audit logs, both can normally be found in `/core/logs`. 1. Encap server audit log. Found at `core/logs/audit.log`. Audit logging for the Encap server. 2. Encap cmd audit log. Found at `core/logs/audit_cmd.log`. Audit logging for the Encap admin commands. :::tip Note Audit logging is by default logging on `INFO` level with the `AUDIT` marker. Previously, this was logged to `ERROR` level to be certain logging was never disabled. Since Encap version 3.18, we now log to `ERROR` only if the appender has not been configured on `INFO` level together with a warning in the log as shown below. ::: ``` 2023-09-27 10:33:51,137 WARN d4040e62-999f-4a46-873f-c949dab70ddb |-[com.encapsecurity.encap.logging.AuditLogger] Log level for Audit log is not set to INFO! 2023-09-27 10:33:51,137 ERROR d4040e62-999f-4a46-873f-c949dab70ddb |+AUDIT-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"ACTIVATION","eventType":"PLATFORM_BEGIN_ACTIVATE","eventStatus":"BEGIN","eventId":"1951dcca-1aa2-4872-a809-ca6c56f0b2eb","sessionId":null,"sessionUuid":"cc4b0aa0-125f-4e47-ab22-583880c451b0","sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","auditLogVersion":4,"requestId":"d4040e62-999f-4a46-873f-c949dab70ddb","registrationId":"152c4a88-b68a-42d6-ba03-f6416cab5b0c","applicationId":"encap","time":"2023-09-27T08:33:51.137UTC","organizationId":"83d1dfb6-2a54-49c7-bde2-acc21b821584","ltime":1695803631137} ``` ## Sending audit logs to system out ### Encap server audit logging To get Encap server audit to print to console add the following to `core/config/logback.xml`. :::tip Note This will not affect other audit log outputs. ::: 1. Replace the following: ```xml ``` With: ```xml ``` 2. This will give the following style of output in the console (if the server is started with the foreground option `./run.sh start -f`): ``` 2023-09-27 10:28:58,393 INFO 16b80d7f-8a17-44ef-a7d7-58e308858bfb |+AUDIT-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"AUTHENTICATION","eventType":"PLATFORM_BEGIN_AUTHENTICATE","eventStatus":"BEGIN","eventId":"d42b79cc-7190-4b66-95a0-3c01a5bbd766","sessionId":null,"sessionUuid":"34620d5b-e0da-48a9-9d1e-b88fb405064e","sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","auditLogVersion":4,"requestId":"16b80d7f-8a17-44ef-a7d7-58e308858bfb","registrationId":"a0de36a1-efba-4039-b8c2-39d17f6124eb","applicationId":"encap","time":"2023-09-27T08:28:58.393UTC","organizationId":"83d1dfb6-2a54-49c7-bde2-acc21b821584","ltime":1695803338393} 2023-09-27 10:28:58,399 INFO 16b80d7f-8a17-44ef-a7d7-58e308858bfb |+AUDIT-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"AUTHENTICATION","eventType":"PLATFORM_BEGIN_AUTHENTICATE","eventStatus":"SUCCESS","eventId":"d42b79cc-7190-4b66-95a0-3c01a5bbd766","sessionId":245,"sessionUuid":"6a42ff47-ce7a-4c09-9015-1309f0658475","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":6,"clientAddress":"127.0.0.1","metaInfo":"","auditLogVersion":4,"requestId":"16b80d7f-8a17-44ef-a7d7-58e308858bfb","registrationId":"a0de36a1-efba-4039-b8c2-39d17f6124eb","applicationId":"encap","time":"2023-09-27T08:28:58.399UTC","organizationId":"83d1dfb6-2a54-49c7-bde2-acc21b821584","ltime":1695803338399} 2023-09-27 10:28:58,423 INFO ac06b70a-287b-46aa-89f9-23096e35fe74 |+AUDIT-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"ADMIN","eventType":"PLATFORM_GET_SESSION","eventStatus":"BEGIN","eventId":"572ddca5-56d1-47aa-bd4d-484c1ff97083","sessionId":245,"sessionUuid":"6a42ff47-ce7a-4c09-9015-1309f0658475","sessionStatus":null,"altId":"sessionUuid=6a42ff47-ce7a-4c09-9015-1309f0658475","responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","auditLogVersion":4,"requestId":"ac06b70a-287b-46aa-89f9-23096e35fe74","registrationId":"a0de36a1-efba-4039-b8c2-39d17f6124eb","applicationId":"encap","time":"2023-09-27T08:28:58.423UTC","organizationId":"83d1dfb6-2a54-49c7-bde2-acc21b821584","ltime":1695803338423} 2023-09-27 10:28:58,431 INFO ac06b70a-287b-46aa-89f9-23096e35fe74 |+AUDIT-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"ADMIN","eventType":"PLATFORM_GET_SESSION","eventStatus":"SUCCESS","eventId":"572ddca5-56d1-47aa-bd4d-484c1ff97083","sessionId":245,"sessionUuid":"6a42ff47-ce7a-4c09-9015-1309f0658475","sessionStatus":null,"altId":"sessionUuid=6a42ff47-ce7a-4c09-9015-1309f0658475","responseTime":8,"clientAddress":"127.0.0.1","metaInfo":"","auditLogVersion":4,"requestId":"ac06b70a-287b-46aa-89f9-23096e35fe74","registrationId":"a0de36a1-efba-4039-b8c2-39d17f6124eb","applicationId":"encap","time":"2023-09-27T08:28:58.431UTC","organizationId":"83d1dfb6-2a54-49c7-bde2-acc21b821584","ltime":1695803338431} ``` You can read about the format of the message on the [Encap server logs](/docs/mobile-identity/encap/server/manual/encap-server-logs.mdx) page, under the section [Audit log](/docs/mobile-identity/encap/server/manual/encap-server-logs.mdx#audit-log). ### Encap command audit logging To get Encap command audit to print to console add the following to `core/config/logback-cmd.xml`. :::tip Note This will not affect other audit log outputs (by default `audit-cmd.log`). ::: 1. Replace the following: ```xml %.-1p %-6r %m%n%xEx ``` With: ```xml %-5replace(%marker){'^$', 'STD'}|%d %-5p |-[%c] %m%n%xEx ``` 2. Replace the following: ```xml ``` With: ```xml ``` 3. This will give the following style of output in the console when a command is run (see AUDIT lines amongst the normal output of the command).: ``` ./scripts/manageApiKey.sh create -o 31489d56-5d7d-4d3b-825e-eb1f4d2a986c AUDIT|2023-09-28 10:42:32,248 INFO |-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"ADMIN","eventType":"API_KEY_CREATE","eventStatus":"BEGIN","eventId":"81cdbea5-a40f-45cb-b637-b73bd2899e9a","sessionId":null,"sessionUuid":null,"sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"192.168.1.122","metaInfo":"UserID: 'olaj'; Description: null, Generated from: Command line","auditLogVersion":4,"requestId":null,"registrationId":null,"applicationId":"NA","time":"2023-09-28T08:42:32.210UTC","organizationId":"31489d56-5d7d-4d3b-825e-eb1f4d2a986c","ltime":1695890552210} AUDIT|2023-09-28 10:42:32,283 INFO |-[com.encapsecurity.encap.logging.AuditLogger] {"purpose":"ADMIN","eventType":"API_KEY_CREATE","eventStatus":"SUCCESS","eventId":"81cdbea5-a40f-45cb-b637-b73bd2899e9a","sessionId":null,"sessionUuid":null,"sessionStatus":null,"altId":null,"responseTime":72,"clientAddress":"192.168.1.122","metaInfo":"UserID: 'olaj'; Description: null, Generated from: Command line","auditLogVersion":4,"requestId":null,"registrationId":null,"applicationId":"NA","time":"2023-09-28T08:42:32.282UTC","organizationId":"31489d56-5d7d-4d3b-825e-eb1f4d2a986c","ltime":1695890552282} Your API key id is: a246d741-e608-41a7-af8c-e8d0171b5518 Your API key secret is: 0LiqFm+5kOC3JB7L1W1Z8A== ``` ## Logstash encoded audit logs `LogstashEncoder` is supported in Encap. This allows you to write Encap logs using `LogstashEncoding` and enables you to use the Logstash appenders to push the logs directly to your `Logstash` instance. To set this up, you need to add an appender for this in your `logback.xml` and `logback-cmd.xml`, found in `/core/configs/`. By default, logback is configured to scan for changes to the configuration. If this has not been disabled, then these changes can be done without restarting the server. ### Logback configuration for Logstash **Example: LogstashEncoded audit log to file** ```xml ./logs/stashAudit.log ./logs/stashAudit.%d{yyyy-MM-dd}.log ${AUDIT_LOG_RETAIN_DAYS} ``` **Example: Sending LogstashEncoded audit logs to Logstash** ```xml 0.0.0.0:5000 ``` For more details what appenders Logstash provides, see [GitHub - logfellow/logstash-logback-encoder: Logback JSON encoder and appenders](https://github.com/logstash/logstash-logback-encoder). **Example: Add the new appender to the audit logger** ```xml ``` --- ## Database configuration ## Introduction Before you look into the Encap server's DBMS configuration, you must ensure that the DBMS you have chosen to use is installed and ready for use. This involves getting the system up and running, making sure that its access is restricted, such as by firewall rules and secured by strong passwords, and that a user has been created within the system for use by the Encap server. This user requires full control over a single separate database. Provided the database is created and the user has necessary privileges, the data structure such as tables and columns will be created. With a DBMS configured for use by the Encap server up and running, you can now learn how to configure the Encap server. ## Database Configuration To configure the database connection, edit the file named `encap-db.properties` located in the `/core/config` directory of your unpacked Encap server distribution. Examples exists for MySQL and Oracle in the below chapters. To change the configured DBMS, modify the `encap.db.jdbcUrl` and `encap.db.driverClass` properties to activate a different DBMS driver and point to your DBMS server. If you need to change the authentication credentials towards the DBMS, modify the `encap.db.user` and `encap.db.password` properties to provide the credentials of the user that you have created in your DBMS for use by the Encap server. In the same file, you will also find properties for tuning the database connection pool. :::CustomTable{columnWidths="33% 33% 33%"} | **Property name** | **Description** | **Default value** | | :-- | :-- | :-- | | `encap.db.driverClass` | Name of the driver class | `com.mysql.cj.jdbc.MysqlDataSource` | | `encap.db.jdbcUrl` | Connection URL to the database | `jdbc:mysql://localhost:3306/encap` | | `encap.db.user` | Username for the database | `encap` | | `encap.db.password` | Password for the database | `encap` | | `encap.db.maxPoolSize` | Setting the maximum size of the main transaction pool, including both idle and in-use connections. The total number of connections is determined by the sum of this value and the below `encap.db.log.mainPoolFactor` and `encap.db.supplementary.mainPoolFactor`. | `150` | | `encap.db.log.mainPoolFactor` | Pool size for integrated logging db pool. `encap.db.maxPoolSize` * `encap.db.log.mainPoolFactor` => logging connection pool size. | `0.25` | | `encap.db.supplementary.mainPoolFactor` | Pool size for manual transaction pool. `encap.db.maxPoolSize` * `encap.db.supplementary.mainPoolFactor` => manual transaction connection pool size. | `0.20` | | `encap.db.minimumIdle` | This property controls the minimum number of idle connections that the connection pool tries to maintain. If the idle connections dip below this value, the pool will make a best effort to add additional connections quickly and efficiently. For maximum performance and responsiveness to spike demands, we recommend setting this value same as `encap.db.maxPoolSize`, and instead allowing `HikariCP` to act as `encap.db.maxPoolSize`, in effect making it a fixed size connection pool. | `10` | | `encap.db.idleTimeout` | This property controls the maximum amount of time (in milliseconds) that a connection is allowed to sit idle in the pool. Whether a connection is retired as idle or not is subject to a maximum variation of +30 seconds, and average variation of +15 seconds. A connection will never be retired as idle before this timeout. A value of `0` means that idle connections are never removed from the pool. | `360000` | ::: ## Supported databases ### Database drivers Database drivers for MySQL and Oracle has to be downloaded because their licences doesn't allow the database drivers to be included in the Encap server distribution. Encap server has been tested with Oracle JDBC driver and MySQL Connector of the latest version at time of release. Download the appropriate version from the links below. - Download link for Oracle: [Oracle JDBC drivers](https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html) - Download link for MySQL: [MySQL JDBC driver](https://dev.mysql.com/downloads/connector/j/) The database driver must be placed under both `/core/lib` and `/core/scripts/lib`, where `` refers to your unpacked Encap server distribution package. ### MySQL Encap server requires the binary log format to be set to row. In the mysql configuration file `my.cnf` (default to `/etc/mysql/my.cnf`), you have to change or insert: ```sql binlog_format = row ``` #### Identifier Case Sensitivity in mysql Encap server requires that the `lower_case_table_names` MySQL system variable is set to `0` which means that table and database names are stored on disk using the casing specified in the `CREATE TABLE` or `CREATE DATABASE` statement. Name comparisons are case-sensitive. **Example: MySQL - Create user for Encap server** ```sql $ mysql -u root -p create user 'encap'@'localhost' identified by 'encap'; create database if not exists encap; grant all privileges on encap.* to 'encap'@'localhost' with grant option; ``` Database configuration for MySQL pointing to localhost with the default port (3306) of an MySQL installation. **Example: Encap DB configuration file `./core/config/encap-db.properties` for MySQL** ```sql # DB address and user encap.db.driverClass=com.mysql.cj.jdbc.MysqlDataSource encap.db.jdbcUrl=jdbc:mysql://localhost:3306/encap encap.db.user=encap encap.db.password=encap # Pool tuning encap.db.maxPoolSize=50 encap.db.minimumIdle=10 encap.db.idleTimeout=360000 # Pool size for integrated logging db pool # encap.db.maxPoolSize * encap.db.log.mainPoolFactor => logging connection pool size encap.db.log.mainPoolFactor=0.25 # encap.db.maxPoolSize * encap.db.supplementary.mainPoolFactor => manual transaction connection pool size encap.db.supplementary.mainPoolFactor=0.20 ``` #### MySQL database connection pool parameters The MySQL maximum number of database connections is 151 by default [MySQL :: MySQL 8.0 Reference Manual :: B.3.2.5 Too many connections](https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html). Maximum amount of database connections for the Encap server can be calculated by: ``` encap.db.maxPoolSize + (encap.db.maxPoolSize * encap.db.log.mainPoolFactor) + (encap.db.maxPoolSize * encap.db.supplementary.mainPoolFactor) 50 + (50 * 0.25) + (50 * 0.20) ≈ 75 ``` To set the maximum number of database connections according to the configuration in encap-db.properties, calculate the total connections which are maxPoolSize +the following MySQL constructs can be used: ```sql mysql> SET GLOBAL max_connections = 75; ``` To make this setting persistent, edit the MySQL configuration file my.cnf, under [mysqld] section: ```sql [mysqld] max_connections = 75 ``` The configuration file my.cnf can be found by help of ```sql mysqld --help --verbose 2>/dev/null | grep my.cnf ``` #### MySQL SSL driver options If you experience MySQL SSL warnings in the logs, looking like this (There are some variants it does not have to be verbatim): >Establishing SSL connection without server's identity verification is not recommended. According to MySQL requirements, SSL connection must be established by default if the explicit option isn't set. For compliance with existing applications not using SSL the verifyServerCertificate property is set to `false`. You need either to explicitly disable SSL by setting `useSSL=false`, or set `useSSL=true` and provide truststore for server certificate verification. This is probably caused by that you either don't have built-in support for SSL on your MySQL server, or it is disabled. You can prevent this warning to appear in the logs by enabling SSL on the server or modifying the JDBC URL and adding the query parameters: `useSSL=false`, in the config file `encap-db.properties`. **Example: Explicit disabled ssl on jdbc client/driver** ``` encap.db.jdbcUrl=jdbc:mysql://localhost:3306/encap?useSSL=false ``` How to enable SSL on MySQL servers: [How To Configure SSL/TLS for MySQL on Ubuntu 16.04 | DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-configure-ssl-tls-for-mysql-on-ubuntu-16-04). ### Oracle Example setup for Encap server user in Oracle. **Example: Oracle - Create tablespace and user for Encap server** ```sql $ sqlplus "/ as sysdba" /* oracle-create-tablespace.sql */ prompt create tablespace ENCAP_DATA create tablespace ENCAP_DATA logging datafile '/opt/oracle/oradata/dbconfig/ORCL/ORCL_encap_data.dbf' size 5M autoextend on next 5M maxsize 2048M extent management local uniform size 1M segment space management auto ; /* oracle-create-user.sql */ create user encap identified by encap default tablespace ENCAP_DATA temporary tablespace temp quota unlimited on ENCAP_DATA ; grant connect, create sequence, create view, alter session, create table, create procedure to encap; ``` Database configuration for Oracle pointing to localhost with the default port (1521) of an Oracle installation. **Example: Encap DB configuration file `./core/config/encap-db.properties` for Oracle** ``` # DB address and user encap.db.driverClass=oracle.jdbc.pool.OracleDataSource encap.db.jdbcUrl=jdbc:oracle:thin:@localhost:1521:xe encap.db.user=encap encap.db.password=encap # Pool tuning encap.db.maxPoolSize=50 encap.db.minimumIdle=10 encap.db.idleTimeout=360000 # Pool size for integrated logging db pool # encap.db.maxPoolSize * encap.db.log.mainPoolFactor => logging connection pool size encap.db.log.mainPoolFactor=0.25 # encap.db.maxPoolSize * encap.db.supplementary.mainPoolFactor => manual transaction connection pool size encap.db.supplementary.mainPoolFactor=0.20 ``` #### Oracle database connection pool parameters Here are some parameters typically used for tuning. Note that the links may not be to your Oracle version, so you should look at the documentation for these flags for your specific version. - The maximum number of database connections is equal to the maximum number of PROCESSES [Database Reference](https://docs.oracle.com/database/121/REFRN/GUID-B757AF80-DA38-4167-A914-FE376A3AD4FE.htm#REFRN10175). - Maximum number of concurrent SESSIONS [Database Reference](https://docs.oracle.com/database/121/REFRN/GUID-52804B5A-164F-44F3-8980-F2593B58D807.htm#REFRN10197) - Maximum number of concurrent TRANSACTIONS [Database Reference](https://docs.oracle.com/cd/B19306_01/server.102/b14237/initparams219.htm#REFRN10222). Maximum amount of database connections for the Encap server can be calculated by: ``` encap.db.maxPoolSize + (encap.db.maxPoolSize * encap.db.log.mainPoolFactor) + (encap.db.maxPoolSize * encap.db.supplementary.mainPoolFactor) 50 + (50 * 0.25) + (50 * 0.20) ≈ 75 ``` To set the number of database connections according to `maxPoolSize` in `encap-db.properties`, the following Oracle constructs can be used, assuming Oracle startup is done with an Oracle server parameter binary file (SPFILE): ``` alter system set processes = 75 scope = spfile; alter system set sessions = 100 scope = spfile; alter system set transactions = 125 scope = spfile; shutdown immediate; startup; ``` For Oracle startup with a text based PFILE as argument to the startup command, the processes, sessions and transaction parameters can be set in the PFILE, and effectuated by an Oracle instance restart. --- ## Encap server logs ## Server log This file contains all log messages from the running server. With the exception of audit messages. The _current log file_ applies to the running Encap server instance, or last running Encap server instance if the server is stopped. Files with a date in the file format are archived log files and may be safely moved elsewhere. ### Log configuration `/core/config/` contains the `logback.xml` file for configuration of logging: :::CustomTable{columnWidths="25% 50% 25%"} | **Property name** | **Description** | **Default value** | | :-- | :-- | :-- | | `LOG_LEVEL` | General log level. It can be useful to set this to INFO while setting up the environment, but since INFO generates large amounts of logs it is not recommended in production. Fine tuning of log levels can be done by configuring the individual loggers further down in the file. | `WARN` | | `APPLICATION_LOG_RETAIN_DAYS` | Days to keep application logs before deleting them. | `200` | | `AUDIT_LOG_RETAIN_DAYS` | Days to keep audits log before deleting them. Defaults to 10 years (3650 days). | `3650` | | `CLIENT_ERROR_LOG_RETAIN_DAYS` | Days to keep client error logs before deleting them. | `30` | | `CLIENT_REQUEST_FIELDS` | Smart device client request fields to be included in debug log. If not present or set to empty string, no request fields will be logged. | | ::: ### Current log, file format The file is called `stderrout.log`. ### Archived log file format The archived log file format is given as `stderrout-yyyy-MM-dd.log`, where: - **yyyy**: Year - **MM**: Month of year - **dd**: Day of month The default number of days to keep the logs is `200`. ## Audit Log Contains all audit log messages. There exists two audit log files: - The `audit.log` that contains all logs written by the Encap server. - The `audit_cmd.log` that contains all logging from running command scripts: - `manageApiKey.sh` - `manageOrganization.sh` Audit logging is done for all incoming calls into the Encap server and for all outgoing calls from the Encap server (with some exceptions). - **Name format**: - `audit..log` (latest log is `audit.log`) - `audit_cmd..log` (latest log is `audit_cmd.log`) - **Default days to keep logs**: 3650 (10 years) Audit logging to file is enabled by default. The logger below is set in `logback.xml`: ```xml ``` ## Audit log file entry examples ``` 2025-10-09 15:42:42,231 d65b349b-4ce6-4191-a709-c15d299f53ee AUDIT {"eventType":"REST_START_ACTIVATION","eventStatus":"BEGIN","eventId":"7c04e019-9cdd-4bf1-9979-5e76f5ef4149","userId":null,"sessionId":null,"sessionUuid":null,"sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"d65b349b-4ce6-4191-a709-c15d299f53ee","registrationId":null,"applicationId":"encap","time":"2025-10-09T13:42:42.231UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362231} 2025-10-09 15:42:42,234 d65b349b-4ce6-4191-a709-c15d299f53ee AUDIT {"eventType":"REST_START_ACTIVATION","eventStatus":"SUCCESS","eventId":"7c04e019-9cdd-4bf1-9979-5e76f5ef4149","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":3,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"d65b349b-4ce6-4191-a709-c15d299f53ee","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.234UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362234} 2025-10-09 15:42:42,247 7c5209e3-7be6-4bac-a622-b0e6a29b5afe AUDIT {"eventType":"DEVICE_START_ACTIVATION","eventStatus":"BEGIN","eventId":"918c96f7-3f02-4735-b43d-b3e1a99fdd43","userId":null,"sessionId":null,"sessionUuid":null,"sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"7c5209e3-7be6-4bac-a622-b0e6a29b5afe","registrationId":null,"applicationId":"encap","time":"2025-10-09T13:42:42.247UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362247} 2025-10-09 15:42:42,250 7c5209e3-7be6-4bac-a622-b0e6a29b5afe AUDIT {"eventType":"DEVICE_START_ACTIVATION","eventStatus":"SUCCESS","eventId":"918c96f7-3f02-4735-b43d-b3e1a99fdd43","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":3,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"7c5209e3-7be6-4bac-a622-b0e6a29b5afe","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.250UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362250} 2025-10-09 15:42:42,261 39e237b3-cbb4-4890-9a7e-a7100f26e1f7 AUDIT {"eventType":"DEVICE_FINISH_ACTIVATION","eventStatus":"BEGIN","eventId":"68bcf052-2215-4872-a240-3b67f1041640","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"activateAuthMethods=[DEVICE_PIN, DEVICE]","requestId":"39e237b3-cbb4-4890-9a7e-a7100f26e1f7","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.261UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362261} 2025-10-09 15:42:42,263 39e237b3-cbb4-4890-9a7e-a7100f26e1f7 AUDIT {"eventType":"DEVICE_FINISH_ACTIVATION","eventStatus":"SUCCESS","eventId":"68bcf052-2215-4872-a240-3b67f1041640","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":1,"clientAddress":"127.0.0.1","metaInfo":"activateAuthMethods=[DEVICE_PIN, DEVICE]","requestId":"39e237b3-cbb4-4890-9a7e-a7100f26e1f7","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.263UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362263} 2025-10-09 15:42:42,275 bd56ec36-fa67-4ea3-bb3c-0dc377c377f5 AUDIT {"eventType":"REST_GET_SESSION","eventStatus":"BEGIN","eventId":"34849291-5e1e-4e0b-987f-2ae4bde6b08f","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"SUCCESS","altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"bd56ec36-fa67-4ea3-bb3c-0dc377c377f5","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.275UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362275} 2025-10-09 15:42:42,277 bd56ec36-fa67-4ea3-bb3c-0dc377c377f5 AUDIT {"eventType":"REST_GET_SESSION","eventStatus":"SUCCESS","eventId":"34849291-5e1e-4e0b-987f-2ae4bde6b08f","userId":null,"sessionId":1537,"sessionUuid":"1f9b5954-8b23-41fb-86fa-f306c48d3a95","sessionStatus":"SUCCESS","altId":null,"responseTime":1,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"bd56ec36-fa67-4ea3-bb3c-0dc377c377f5","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.277UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362277} 2025-10-09 15:42:42,286 088a6d84-9aac-4301-9594-f34e1461b200 AUDIT {"eventType":"REST_START_AUTHENTICATION","eventStatus":"BEGIN","eventId":"52817397-2cd1-45c3-971e-034ae89d0996","userId":null,"sessionId":null,"sessionUuid":null,"sessionStatus":null,"altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"088a6d84-9aac-4301-9594-f34e1461b200","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.286UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362286} 2025-10-09 15:42:42,288 088a6d84-9aac-4301-9594-f34e1461b200 AUDIT {"eventType":"REST_START_AUTHENTICATION","eventStatus":"SUCCESS","eventId":"52817397-2cd1-45c3-971e-034ae89d0996","userId":null,"sessionId":1538,"sessionUuid":"86300d55-39df-420a-92fe-7c729a2f13c9","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":2,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"088a6d84-9aac-4301-9594-f34e1461b200","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.288UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":null,"clientVersion":null,"operatingSystemType":null,"faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362288} 2025-10-09 15:42:42,301 513d91f9-982d-4470-8a6d-0d954868a7ca AUDIT {"eventType":"DEVICE_START_AUTHENTICATION","eventStatus":"BEGIN","eventId":"f783a2df-f56b-4a00-8b84-715fb142d553","userId":null,"sessionId":1538,"sessionUuid":"86300d55-39df-420a-92fe-7c729a2f13c9","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"513d91f9-982d-4470-8a6d-0d954868a7ca","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.301UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":"DEVICE_PIN","clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362301} 2025-10-09 15:42:42,303 513d91f9-982d-4470-8a6d-0d954868a7ca AUDIT {"eventType":"DEVICE_START_AUTHENTICATION","eventStatus":"SUCCESS","eventId":"f783a2df-f56b-4a00-8b84-715fb142d553","userId":null,"sessionId":1538,"sessionUuid":"86300d55-39df-420a-92fe-7c729a2f13c9","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":1,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"513d91f9-982d-4470-8a6d-0d954868a7ca","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.303UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":"DEVICE_PIN","clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362303} 2025-10-09 15:42:42,329 8a863db2-9855-4f04-9d84-d87f830031c5 AUDIT {"eventType":"DEVICE_FINISH_AUTHENTICATION","eventStatus":"BEGIN","eventId":"c4027b36-2c8d-48de-8a3c-ca40542c47b6","userId":null,"sessionId":1538,"sessionUuid":"86300d55-39df-420a-92fe-7c729a2f13c9","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":0,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"8a863db2-9855-4f04-9d84-d87f830031c5","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.329UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":"DEVICE_PIN","clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362329} 2025-10-09 15:42:42,333 8a863db2-9855-4f04-9d84-d87f830031c5 AUDIT {"eventType":"DEVICE_FINISH_AUTHENTICATION","eventStatus":"SUCCESS","eventId":"c4027b36-2c8d-48de-8a3c-ca40542c47b6","userId":null,"sessionId":1538,"sessionUuid":"86300d55-39df-420a-92fe-7c729a2f13c9","sessionStatus":"IN_PROGRESS","altId":null,"responseTime":4,"clientAddress":"127.0.0.1","metaInfo":"","requestId":"8a863db2-9855-4f04-9d84-d87f830031c5","registrationId":"0bda22da-4393-4e44-b332-281c14ceea13","applicationId":"encap","time":"2025-10-09T13:42:42.333UTC","organizationId":"04cab507-9713-4c2d-943f-95997b243f9e","traceId":"00000000000000000000000000000000","authMethod":"DEVICE_PIN","clientVersion":"3.21.0","operatingSystemType":"Android","faceMapId":null,"errorMessage":null,"auditLogVersion":8,"ltime":1760017362333} ``` ### Audit log v8 fields :::CustomTable{columnWidths="25% 75%"} | Field name | Description | | :-- | :-- | | `eventType` | The type of event for this audit. For possible values, see the table under the [Event type](#event-type) section below. | | `eventStatus` | The status of the event. This can be either `BEGIN`, `SUCCESS` or `FAILURE`. | | `time` | The timestamp when the audit event was created. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSS'UTC'`. | | `lTime` | The time of the audit event. Returned in UTC. | | `eventId` | The unique ID of this event. There will normally be two audit entries for each event; one to begin the audit, and one to end the audit. These can be correlated using this ID. | | `sessionId` | The session ID of the session related to this event, if any. | | `sessionUuid` | The session UUID of the session related to this event, if any. | | `sessionStatus` | The session status of the session related to this event, if any. | | `registrationId` | The ID of the registration entity related to the event. | | `altId` | The alternative ID related to this event. The ID type is prefixed to the identifier. This could be the `pushtoken` ID or other identifiers that might correlate to the event. | | `responseTime` | The time from start of event to event finished in ms. **Note**: This is not the same as the request time. | | `clientAddress` | The address of client on the request originating this event. One request might originate more than one event. | | `auditLogVersion` | The version of the audit log used. | | `requestId` | The unique identifier for the request originating this event. One request might originate more than one event. In the database, it is stored in the column `requestCorrelationId`. | | `applicationId` | The ID of the application configuration related to this event, if any. | | `metaInfo` | The meta information related to the event that does not have its own field. **Note**: This could be reasons for an event failure, details for an event, or admin user IDs for an event. | | `organizationId` | The organisation ID related to this event. | | `traceId` | The OTEL traceId identifier if an OTEL agent has been installed. Defaults to `00000000000000000000000000000000`. | | `userId` | The ID of the user performing the operation. This is the user that is running the command-line tool. | | `authMethod` | The authentication method used for authentication in this operation. | | `clientVersion` | The version of the Encap client SDK. | | `operatingSystemType` | The operating system of the client. | | `faceMapId` | The `faceMapId` for this event if server-side face authentication is used. | | `errorMessage` | The error message for this event, if any. | ::: #### Event type :::tip Note - **Originators** are those triggering the event. - Service providers trigger events through either the WS API or the REST API. - Operations trigger events through either the Encap administration UI or management shell scripts. - **Recipients** are those handling the event. ::: :::CustomTable{columnWidths="30% 15% 15% 40%"} | Name | Originator | Recipient | Description | | :-- | :-- | :-- | :-- | | `DEVICE_START_ACTIVATION` | Smart device | Encap server | Start the activation process, or continue if started by the service provider. | | `DEVICE_FINISH_ACTIVATION` | Smart device | Encap server | Finish the activation process. | | `DEVICE_START_AUTHENTICATION` | Smart device | Encap server | Start the authentication, or continue if started by the service provider. | | `DEVICE_FINISH_AUTHENTICATION` | Smart device | Encap server | Finish the authentication process. | | `DEVICE_LOAD_CONFIG` | Smart device | Encap server | Get application specific configuration. | | `DEVICE_START_ADD_OR_UPDATE_AUTH_METHOD` | Smart device | Encap server | Start the process of adding additional factors to an existing registration. | | `DEVICE_FINISH_ADD_OR_UPDATE_AUTH_METHOD` | Smart device | Encap server | Finish the process of adding additional factors to an existing registration. | | `DEVICE_START_DEACTIVATION` | Smart device | Encap server | Start the process of removing one or all factors from an existing registration. | | `DEVICE_FINISH_DEACTIVATION` | Smart device | Encap server | Finish the process of removing one or all factors from an existing registration. | | `DEVICE_CANCEL_CURRENT_SESSION` | Smart device | Encap server | Cancel an active session, initiated from the device. | | `DEVICE_START_ADD_OR_UPDATE_RECOVERY` | Smart device | Encap server | Start set up recovery for a device. | | `DEVICE_FINISH_ADD_OR_UPDATE_RECOVERY` | Smart device | Encap server | Finish set up recovery for a device. | | `DEVICE_START_PERFORM_RECOVERY` | Smart device | Encap server | Start perform recovery for a device. | | `DEVICE_FINISH_PERFORM_RECOVERY` | Smart device | Encap server | Finish perform recovery for a device. | | `DEVICE_START_DELETE_RECOVERY` | Smart device | Encap server | Start delete existing recovery configuration for a device. | | `DEVICE_FINISH_DELETE_RECOVERY` | Smart device | Encap server | Finish delete existing recovery configuration for a device. | | `DEVICE_GET_SERVER_SIDE_FACE_INIT_DATA` | Smart device | Encap server | Get the initialisation data used for performing a server-side face authentication operation. | | `DEVICE_ENROL_SERVER_SIDE_FACE` | Smart device | Encap server | Perform enrolment of server-side face authentication. | | `DEVICE_AUTHENTICATE_SERVER_SIDE_FACE` | Smart device | Encap server | Perform an authentication with server-side face authentication. | | `DEVICE_RECOVER_SERVER_SIDE_FACE` | Smart device | Encap server | Recover server-side face authentication credentials as part of a recovery flow. | | `DEVICE_DELETE_SERVER_SIDE_FACE` | Smart device | Encap server | Delete server-side-face authentication as a result of deactivating the registration. | | `DEVICE_REPORT_ERROR` | Smart device | Encap server | Report a client-side error from the smart device. | | `REST_START_ACTIVATION` | Service provider | Encap server | Start the activation process. | | `REST_START_AUTHENTICATION` | Service provider | Encap server | Start the authentication process. | | `REST_IS_LOCKED` | Service provider | Encap server | Check the lock status for a single registration. | | `REST_LOCK` | Service provider | Encap server | Lock a registration. | | `REST_UNLOCK` | Service provider | Encap server | Unlock a registration. | | `REST_DEACTIVATE` | Service provider | Encap server | Remove a registered device. | | `REST_CANCEL_CURRENT_SESSION` | Service provider | Encap server | Cancel an active session, initiated from the REST API. | | `REST_GET_SESSION` | Service provider | Encap server | Get session details for a specific session. | | `REST_GET_SESSIONS_FOR_DEVICE` | Service provider | Encap server | List all sessions for a device. | | `REST_GET_SESSIONS_FOR_DEVICES` | Service provider | Encap server | List all sessions for one or more devices. | | `REST_GET_DEVICE_INFO` | Service provider | Encap server | Get device information for a device. | | `REST_GET_LOCK` | Service provider | Encap server | Get lock information for a device. | | `REST_SET_RECOVERY_LOCK` | Service provider | Encap server | Set or clear the recovery lock for a device. | | `REST_GET_DEVICE_HASH_BLOCKLIST` | Service provider | Encap server | Check if a device hash is blocklisted. | | `REST_ADD_DEVICE_HASH_TO_BLOCKLIST` | Service provider | Encap server | Add a device hash to the blocklist. | | `REST_DELETE_DEVICE_HASH_FROM_BLOCKLIST` | Service provider | Encap server | Remove a device hash from the blocklist. | | `REST_ADD_APP_CONFIG` | Operations, Service provider | Encap server | Add application configuration. | | `REST_UPDATE_APP_CONFIG` | Operations | Encap server | Update application configuration. | | `REST_REMOVE_APP_CONFIG` | Operations, Service provider | Encap server | Remove an existing application configuration. | | `REST_LIST_APP_CONFIGS` | Operations, Service provider | Encap server | List all application configurations. | | `REST_GET_APP_CONFIG` | Operations, Service provider | Encap server | Print a specified application configuration. | | `REST_CREATE_API_KEY` | Operations | Encap server | Create API key. | | `REST_DELETE_API_KEY` | Operations | Encap server | Delete API key. | | `REST_GET_API_KEY` | Operations | Encap server | Get API key. | | `REST_LIST_API_KEYS` | Operations | Encap server | List API keys. | | `REST_CREATE_KEY` | Operations, Service provider | Encap server | Add a certificate or key. | | `REST_DELETE_KEY` | Operations, Service provider | Encap server | Delete a certificate or key. | | `REST_GET_KEY` | Operations, Service provider | Encap server | Get information about a specific certificate or key. | | `REST_LIST_KEYS` | Operations | Encap server | List certificates or keys. | | `REST_ADD_ORGANIZATION` | Operations, Service provider | Encap server | Create an organisation. | | `REST_LIST_ORGANIZATIONS` | Operations, Service provider | Encap server | Get all organisations. | | `REST_DELETE_ORGANIZATION` | Operations, Service provider | Encap server | Delete an organisation. | | `REST_REQUEST_DEVICE_STATISTICS` | Service provider | Encap server | Request the generation of device statistics. | | `REST_GET_DEVICE_STATISTICS` | Service provider | Encap server | Fetch the generated device statistics. | | `REST_GET_DB_CLEANUP_DETAILS` | Service provider | Encap server | Get all database cleanup statistics. | | `REST_LIST_DB_CLEANUP_DETAILS` | Service provider | Encap server | Get database cleanup details. | | `REST_GET_GEOFENCING_CONFIG` | Service provider | Encap server | Get geofencing configuration for a device. | | `REST_UPDATE_GEOFENCING_CONFIG` | Service provider | Encap server | Update geofencing configuration for a device. | | `REST_DELETE_GEOFENCING_CONFIG` | Service provider | Encap server | Delete geofencing configuration for a device. | | `REST_CREATE_DEVICE_GROUP` | Encap server, Service provider | Encap server | Create a device group. | | `REST_UPDATE_DEVICE_GROUP` | Service provider | Encap server | Update a device group. | | `REST_DELETE_DEVICE_GROUP` | Service provider | Encap server | Delete a device group. | | `REST_GET_DEVICE_GROUP` | Service provider | Encap server | Get information about a device group. | | `REST_GET_DEVICE_GROUP_DETAILS` | Service provider | Encap server | Get the registered devices in a device group. | | `SERVER_DELETE_SERVER_SIDE_FACE` | Encap server | Service provider | Delete server-side face authentication as a result of deactivating the registration from the REST API. | | `SERVER_SEND_PUSH_GOOGLE` | Encap server | Google | Send push to the smart device. | | `SERVER_SEND_PUSH_APPLE` | Encap server | Apple | Send push to the smart device. | | `SERVER_CALLBACK_AUTHENTICATION` | Encap server | Service provider | Notify the service provider about a completed authentication. | | `SERVER_CALLBACK_ACTIVATION` | Encap server | Service provider | Notify the service provider about a completed activation. | | `SERVER_CALLBACK_EXPIRATION` | Encap server | Service provider | Notify the service provider about an expired session. | | `SERVER_EVENT_CALLBACK_DEVICE_LOCKED` | Encap server | Service provider | Notify the service provider about a device locked operation. | | `SERVER_EVENT_CALLBACK_DEVICE_UNLOCKED` | Encap server | Service provider | Notify the service provider about a device unlocked operation. | | `SERVER_EVENT_CALLBACK_DEVICE_ACTIVATION` | Encap server | Service provider | Notify the service provider about a device activation operation. | | `SERVER_EVENT_CALLBACK_DEVICE_DEACTIVATED` | Encap server | Service provider | Notify the service provider about a device deactivation operation. | | `SERVER_EVENT_CALLBACK_DEVICE_AUTHENTICATION` | Encap server | Service provider | Notify the service provider about a device authentication operation. | | `SERVER_EVENT_CALLBACK_DEVICE_ADD_OR_UPDATE_RECOVERY` | Encap server | Service provider | Notify the service provider about a device add or update recovery operation. | | `SERVER_EVENT_CALLBACK_DEVICE_PERFORM_RECOVERY` | Encap server | Service provider | Notify the service provider about a device perform recovery operation. | | `SERVER_EVENT_CALLBACK_DEVICE_DELETE_RECOVERY` | Encap server | Service provider | Notify the service provider about a device delete recovery operation. | ::: ## Request Log Request logs are a record of the requests that the Encap server has processed. There is one entry per request received. This is in the common log format (NCSA), making it convenient to analyse them. A standard request log entry includes the: - Client IP address - Date - Method - URL - Result - Size - Referrer - User agent - Latency The Encap server provides a request log in a common log format. The format can be configured in the Encap instance configuration. The request log appender writes to the `request.log` file found in the logs folder. The appender has a size based rolling policy of 10 MB, and it keeps the last 10 files as zip files with file pattern `request..log.zip`. The appender configuration can be updated in the `logback.xml` file. ```xml ./logs/request.log request.%i.log.zip 1 10 10MB %d %X{requestCorrelationId} %m%n ``` The request logger is by default disabled with level `OFF` in the `logback.xml` file. To enable request logging, change the level to `INFO`. ```xml ``` ## Monitoring The Encap server is monitoring: - Class loading - JVM memory - JVM GC - JVM threads - CPU metrics - Jetty thread pool - Jetty connection statistics The Encap server also monitors statistics for: - Event callback - Performance per operation - DB cleanup ### Prometheus The Encap server has optional support to output metrics to Prometheus. For configuration, look for parameters beginning with Prometheus in the list of available configuration parameters on the [Server configuration](/docs/mobile-identity/encap/server/manual/server-configuration.mdx). :::info Want to learn more? You can read more about Prometheus in their [developer documentation](https://prometheus.io/docs/introduction/overview). ::: ### Values #### JVM memory :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `jvm.buffer.count` | An estimate of the number of buffers in the pool. | | `jvm.buffer.memory.used` | An estimate of the memory that the Java virtual machine is using for this buffer pool. | | `jvm.buffer.total.capacity` | An estimate of the total capacity of the buffers in this pool. | | `jvm.memory.used` | The amount of used memory. | | `jvm.memory.committed` | The amount of memory in bytes that is committed for the Java virtual machine to use. | | `jvm.memory.max` | The maximum amount of memory in bytes that can be used for memory management. | ::: #### JVM garbage collector :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `jvm.gc.max.data.size` | Max size of long-lived heap memory pool. | | `jvm.gc.live.data.size` | Size of long-lived heap memory pool after reclamation. | | `jvm.gc.memory.allocated` | Incremented for an increase in the size of the (young) heap memory pool after one GC to before the next. | | `jvm.gc.memory.promoted` | Count of positive increases in the size of the old generation memory pool before GC to after GC. | | `jvm.gc.concurrent.phase.time` | Time spent in concurrent phase. | | `jvm.gc.pause` | Time spent in GC pause. | ::: #### JVM thread :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `jvm.threads.peak` | The peak live thread count since the Java virtual machine started or peak was reset. | | `jvm.threads.daemon` | The current number of live daemon threads. | | `jvm.threads.live` | The current number of live threads including both daemon and non-daemon threads. | | `jvm.threads.states` | The current number of threads. | ::: #### JVM class loader :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `jvm.classes.loaded` | The number of classes that are currently loaded in the Java virtual machine. | | `jvm.classes.unloaded` | The total number of classes unloaded since the Java virtual machine was started. execution | ::: #### Jetty server :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `jetty.server.dispatches.open` | Jetty dispatches that are currently in progress. | | `jetty.server.async.dispatches` | Asynchronous dispatches. | | `jetty.server.async.expires` | Asynchronous operations that timed out before completing. | | `jetty.server.async.waits` | Pending asynchronous wait operations. | | `jetty.server.requests` | HTTP requests to the Jetty server. | ::: #### Device :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `encap.device.operation` | Count of device events, with event status and lock status (when failing). | | `encap.device.end2end` | Usage statistics for end-to-end (E2E) keys used per application configuration. | ::: #### Server :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `encap.operations` | Metrics based on the same data as the audit events. Will output metrics for all requests against the server including REST, device, batch or script. Each measurement is tagged with `event_type`, `event_status`, `session_status`, `application_id` and `organization_id`. See the [Event type](#event-type) section for the possible `event_type` values. | ::: #### Event callback :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `encap.callback.event.queue.success` | Count of successful event callbacks. | | `encap.callback.event.queue.failure` | Count of failed event callbacks. | | `encap.callback.event.queue.batch.time` | Time spent to process a single batch of event callbacks. | | `encap.callback.event.queue.size` | Size of the event callback queue. | ::: #### On-demand callback :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `encap.callback.ondemand` | Time and counter metrics for the on-demand callback endpoint. | ::: #### Database cleanup :::CustomTable{columnWidths="35% 65%"} | Metric name | Description | | :-- | :-- | | `encap.db.cleanup.job.time` | Time spent performing the cleanup job, divided by job name and group. | | `encap.db.cleanup.job.rows` | Number of database rows deleted, divided by job name and group. | ::: --- ## HTTP configuration ## Encap server HTTP Configuration ### Smart device environment requirements The following internet protocol access needs to be open for use: :::CustomTable{columnWidths="25% 37.5% 37.5%"} | **Smart device** | **Internet protocol access** | **Comment** | | :-- | :-- | :-- | | Android, iOS | `https://host:port/path/platform-smartdevice` | URL used by the smart device clients. | | Android | `fcm.googleapis.com:443` | Traffic from Encap server to Firebase Cloud Messaging (if used). | | iOS | `api.push.apple.com:443` (PRODUCTION) `api.development.push.apple.com:443` (SANDBOX) | Host/port from Encap server to Apple Push Notifications (if APNS used). | ::: ### Security considerations To limit exposure of the Encap server to the internet, it is recommended to only proxy the specific sub-paths of the server that are used externally. For the paths and functionality that they support, see the list below. :::CustomTable{columnWidths="25% 37.5% 37.5%"} | **Path** | **User** | **Function description** | | :-- | :-- | :-- | | `/platform-smartdevice/client` | Mobile device | iOS and Android devices clients JSON/HTTP interface. Used by device clients since version 3.1. | | `/admin-api` | Service provider admin | Service provider admin REST interface. | | `/api` | Service provider | Service provider REST interface. | ::: ### Load balancing considerations The Encap server supports running multiple Encap server instances behind a load balancer against the same database. This allows for horizontal scaling if performance is an issue, or to decrease downtime. The Encap server does not require the load balancer to use any form of sticky sessions. An Apache httpd configuration for this would look something like this: ``` BalancerMember https://192.168.0.31:11443 route=ha1 BalancerMember https://192.168.0.29:11443 route=ha2 ProxyPass /ha balancer://hacluster/ha ProxyPassReverse /ha balancer://hacluster/ha ``` ## Reverse HTTP Proxy The Encap server provides a web server that is by default configured to bind on ports 9080 and 9443 for serving HTTP and HTTPS requests respectively. For ease of maintenance and to support clustering and fail-over setups, we recommend that you install a reverse proxy server that connects your customers to the Encap server. Alternatively, you can also choose to modify the configuration of the Encap server web server and connect your customers to it directly, without a reverse proxy in between to manage this. The reverse proxy must forward the HTTP Header **X-Forwarded-Proto** to Encap server. For more information, see [List of HTTP header fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields). The Encap server uses this header to determine how to handle forwarded requests. ### Apache 2 HTTP configuration for X-Forward-Proto ``` # /etc/apache2/sites-available/default : # Set X-Forwarded-Proto needed by SAML handling RequestHeader set X-Forwarded-Proto "http" ``` ### Apache 2 HTTPS configuration for X-Forward-Proto ``` # /etc/apache2/sites-available/default-ssl : # Set X-Forwarded-Proto needed by SAML handling RequestHeader set X-Forwarded-Proto "https" ``` ### Forward proxy support for Firebase FCM and Apple APNS push messages The Encap server supports proxying push messages for FCM and Apple APNS when setting the following parameters in `encap-cluster.properties`: #### FCM - `server.fcmProxyServer.host` - `server.fcmProxyServer.port` - `server.fcmProxyServer.proxyType` #### APNS - `server.apnsProxyServer.host` - `server.apnsProxyServer.port` :::tip Full parameter descriptions See parameter table for full description of valid parameter values: **Core cluster configurations**. ::: ### Example proxy config with Apache 2 To enable Apache2 as forward proxy, you need the following mods enabled: ``` proxy, proxy_http, rewrite, deflate, headers, proxy_connect, proxy_html ``` The following config is an example of how the Apache2 server can be set for forward proxying on port 8889: **Example: httpd.conf** ``` ErrorLog ${APACHE_LOG_DIR}/error_forward_proxy.log CustomLog ${APACHE_LOG_DIR}/access_forward_proxy.log combined ProxyRequests On Listen 8889 ``` :::note Note The proxy server needs to support CONNECT. The `proxy_connect` mod is necessary for supporting CONNECT in Apache2. For further information, see **section 5.2** in document [HTTP Upgrade to TLS](https://www.ietf.org/rfc/rfc2817.txt). ::: --- ## Server manual ## About the server manual With this manual, you'll learn how to do the following for a production environment: - How to install an Encap server. - How to set up an Encap server. - How to maintain an Encap server. ## Installation The installation process of an Encap server is efficient due to the pre-packaged distribution archive. You also need to install: - A database management system - A reverse proxy _(optional)_. We will provide the Encap server-specific information that you will need to get the database management system and reverse proxy set up for use with the Encap server. ## Requirements ### Minimum hardware recommendations: - Intel/AMD Quad-core CPU (or similar) - 4 GB RAM - 150 GB disk - 100 Mbit Ethernet ### Software requirements: - Encap server is verified to work on Amazon Linux 2023, Ubuntu 24.04 LTS and Red Hat Enterprise Linux (RHEL) 9.4. - A server with Oracle Java/OpenJDK 21 or 25 installed. - Access to a database server MySQL 8.0 or Oracle 19.3. Either on-premise or in the cloud: AWS RDS, GCP Cloud SQL. - Device client specific requirements which can be found in the device client documentation. - Open files limit must be at least 2048 or higher. ## Guides * [**Quick start guide**](/docs/mobile-identity/encap/server/manual/quick-start-guide): Learn how to install and start the Encap server * [**Configuration**](/docs/mobile-identity/encap/server/manual/server-configuration): Learn how to configure attributes on the Encap server to the needs of your environment * [**Application configuration**](/docs/mobile-identity/encap/server/manual/application-configuration): Learn how to configure the application configuration * [**Database configuration**](/docs/mobile-identity/encap/server/manual/database-configuration): Learn how to configure the database * [**HTTP configuration**](/docs/mobile-identity/encap/server/manual/http-configuration): Learn about HTTP server configuration and reverse HTTP proxy * [**Maintenance**](/docs/mobile-identity/encap/server/manual/server-maintenance): Learn how to maintain the Encap server * [**Encap server logs**](/docs/mobile-identity/encap/server/manual/encap-server-logs): Learn about Encap server logs * [**Audit log configuration**](/docs/mobile-identity/encap/server/manual/audit-log-configuration): Learn how to configure audit logs :::note Need help? If you require assistance or need to report an issue, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Quick start guide(Manual) ## Introduction ### The Encap server distribution First, you need to install the Encap server distribution. The Encap server comes pre-packaged in a ZIP archive that unpacks into a fully self-contained Jetty server. ### Default configuration There is a default configuration in place that should allow you to start the server immediately, provided your database management system is set up to work with these defaults. This guide will also cover the important files within the distribution that may need to be adjusted to work with your environment. ## Installation ### Download The latest version of `encap-distribution` can be found in the [Encap repository](https://nexus.pub.encap.no/). For the folder containing the releases, see [encap-distribution](https://nexus.pub.encap.no/#browse/browse:encap-partner-repository:com%2Fencapsecurity%2Fencap%2Fencap-distribution). #### Supported Java version The Encap server runs on Java 21 or Java 25. ### Unpack Unzip the `encap-distribution` zip file: ``` $ unzip encap-distribution-X.Y.Z.zip Archive: encap-distribution-X.Y.Z.zip creating: encap-distribution-X.Y.Z/ creating: encap-distribution-X.Y.Z/core/ creating: encap-distribution-X.Y.Z/core/config/ creating: encap-distribution-X.Y.Z/core/scripts/ creating: encap-distribution-X.Y.Z/core/scripts/jars/ creating: encap-distribution-X.Y.Z/core/scripts/lib/ creating: encap-distribution-X.Y.Z/core/lib/ ... ``` ### Configure database Ensure database is configured in the file: `/core/config/encap-db.properties`, which is required by the upgrade script. #### Database drivers Download link for Oracle: [Oracle JDBC driver](https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html). Download link for MySQL: [MySQL JDBC driver](https://dev.mysql.com/downloads/connector/j/) The database driver must be placed in both: `/core/lib`, and `/core/scripts/lib`. More information about database setup can be found in the **Encap server Administration Manual** under **The Database Management System**. #### Initialising the database The `initdb.sh` upgrade command is used to initialise an empty database or upgrade an existing Encap database to the newest Encap schema DDL version. Run `./initdb.sh` to see command line help and available options. To initialise the database run the following script: ``` encap-distribution$ ./core/scripts/initdb.sh upgrade ``` ### Start the server and verify startup The Encap server can be started in two modes, using different start scripts. #### Mode 1: Starting in foreground mode 1. Start the Encap server in foreground mode: ``` encap-distribution$ ./core/encap.sh ``` 2. The Encap server will be running until the active cmd session is aborted. This is also the recommended way to use when running in a container. #### Mode 2: Starting using background mode (legacy mode) 1. Start the Encap server by executing the run.sh script. ``` encap-distribution$ ./core/run.sh start ``` 2. Check the log `(./core/logs/stderrout.log)` for warnings and error messages. 3. Stop the server by using the same `run.sh` script. ``` encap-distribution$ ./core/run.sh stop ``` 4. Type `./run.sh` with no parameters to get help and list of flags. :::tip Server log file rollover The server log file has daily rollover set to this pattern `stderrout.%d{yyyy-MM-dd}.log`. ::: ### Troubleshooting If trying to start the Encap server and another instance is running, such as an older version, then the script is not able to detect this. It needs to be stopped manually. ### Virtualisation considerations The Encap server requires a minimum of entropy. It uses `/dev/random` as part of the crypto implementation. If there is not enough entropy in the host system, then the Encap server will periodically pause, waiting for `/dev/random` which will lower performance. --- ## Server configuration ## Introduction All configuration attributes on the Encap server have reasonable default values. This page will show you how to adjust the defaults to the needs of your specific environment, if necessary. ## Server Configuration Encap server configurations is split into two types of configurations. - **Encap cluster wide configuration** - Defined in the folder `config/encap-cluster.properties` - Cluster wide configuration, must be the same for all nodes - Server restart required to make changes go into effect. - **Encap instance configuration** - Defined in the folder `config/encap-instance.properties` - Instance specific - Server restart required to make changes go into effect. ### Cluster configuration Encap server cluster configurations are specified in `/core/config/encap-cluster.properties` within the Encap server distribution directory. There are a vast amount of configuration properties that the Encap server and its device clients use. Most of these properties have reasonable default values which are left commented out in the provided configuration file. You only need the set the values that differs from the default value in the configuration file. Cluster configurations are read from the `encap-cluster.properties` configuration file at the startup of the server and cannot be changed during runtime. The following tables provide an overview of the core configuration parameters used by the Encap server and their default values: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default Value** | | :-- | :-- | :-- | :-- | | `server.rotateSaltKey` | If true the salt key is rotated on every successful authentication allowing the server to synchronise client and server and detect if multiple devices tries to act as the same device. If false the salt key is never rotated. This disables the clone detection but makes it possible to rollback the database without de-syncing devices that has had activity after this was set to false. | `true`, `false` | `TRUE` | | `services.eventCallback.dbPollingInterval` | Maximum interval (in milliseconds) between each poll for new events in db, usually sent immediately. | Integer | `20000` | | `services.eventCallback.dbMaxEventsToFetch` | Max number of events to fetch per poll for a given app config | Integer | `500` | | `services.eventCallback.timeout` | HTTP timeout in milliseconds for event callback requests | Integer | `3000` | | `services.eventCallback.retryInterval` | Initial interval before retrying the callback. `Subsequent_intervals` = `retryInterval` * `numberOfRetries`^3 | Integer | `2000` | | `services.eventCallback.maxRetryCount` | Max number of retries before giving up delivery of the event. Event will be deleted, and an error logged. | Integer | `40` | | `services.eventCallback.queueSizeWarningLimit` | Threshold for when we will start logging warnings and signal failure on the callback monitoring endpoint | Integer | `5000` | | `server.db.batchsize` | The maximum batch size for DB intense operations. | From `1` to `MAXINT` | `100000` | | `server.rest.callback.proxy.hostname` | Set the hostname for the optional rest callback proxy | String | | | `server.rest.callback.proxy.port` | Set the port for the optional rest callback proxy | Integer | | | `server.rest.callback.timeout` | HTTP timeout in milliseconds for rest callback requests | Integer | `3000` | | `server.rest.callback.threadPoolFactor` | The multiplier factor relative to the max jetty thread pool size configuration. This setting is used to determine the max thread pool size for rest callback handling. `jetty.threads.max` * `server.rest.callback.threadPoolFactor` => max size of rest callback handling thread pool | Integer | `2` | | `server.fcmProxyServer.host` | FCM proxy server host name | String | | | `server.fcmProxyServer.port` | FCM proxy server port number | Integer | | | `server.fcmProxyServer.proxyType` | FCM proxy server proxy "type". Valid options are `HTTP` or `SOCKS`. | String | `SOCKS` | | `server.apnsProxyServer.host` | APNS proxy server host name | String | `localhost` | | `server.apnsProxyServer.port` | APNS proxy server port number | Integer | `8889` | | `prometheus.port` | Port on which prometheus actuator is running | Integer | `9100` | | `prometheus.path` | Path name on which prometheus actuator can be accessed | String | `prometheus` | | `prometheus.step` | The step size to use in computing windowed statistics like max. To get the most out of these statistics, align the step interval to be close to your scrape interval. Duration string representation is created using [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html). The format of the string will be `PTnHnMnS` , where n is the relevant hours, minutes or seconds part of the duration. More information about duration string formatting can be found [here](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#toString--). | Duration | `PT1M` | | `prometheus.description` | Defines if meter descriptions should be sent to Prometheus | Boolean | `FALSE` | | `prometheus.histogramFlavor` | Defines histogram type | `Prometheus, VictorianMetrics` | `Prometheus` | | `prometheus.enabled` | Enable prometheus actuator. Requires server restart | Boolean | `FALSE` | | `services.expiredSessionCallback.schedule` | Cron expression for setting the schedule for querying the DB for expired sessions. When expired sessions are found callbacks are sent to the configured callback endpoint. | Cron expression | `* * * * * ?` | | `services.expiredSessionCallback.batchLimit` | Maximum number of sessions to expire and send callbacks for per batch of the expiredSessionCallback job. The expired session callback job can be disabled by setting this value to `0`. | From `0` to `1000` | `100` | | `serverSideFace.adapter.authServerEndpoint` | The authentication server endpoint URL that provides API access tokens for the server-side face adapter for the Encap server. | URL | `https://api.signicat.com/auth/open/connect/token` | | `serverSideFace.adapter.address` | The server-side face adapter URL that the Encap server uses for the server-side face service. | URL | `https://api.signicat.com/server-side-face` | ::: #### DB cleanup configuration :::CustomTable{columnWidths="15% 45% 20% 20%"} | **Property name** | **Description** | **Allowed values** | **Default Value** | | :-- | :-- | :-- | :-- | | `admin.dbCleanup.enabled` | Turn the cleanup job on or off. | `true`, `false` | `true` | | `admin.dbCleanup.daysToKeep` | The number of days to keep data before removing it. | From `0` to `MAXINT` | `3650` (10 years) | | `admin.dbCleanup.schedule` | Cron expression setting when the database cleanup job should run. See [Tutorial 6](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html) for exact syntax. **Note**: To minimise the work for each run and reduce the impact on system performance, we recommend that you run it daily during the time of lowest load. | See description | 0 0 0 * * ? (Daily at midnight) | | `admin.dbcleanup.device.maxSessionsToKeep` | The maximum number of sessions to keep for a given registration, before `admin.dbCleanup.daysToKeep` kicks in. **Note**: A default value is not set, which means unlimited. | From `0` to `MAXINT` | | | `admin.dbcleanup.device.batchSize` | The maximum number of sessions to delete upon an incoming authentication request for a given device. **Note**: This will only have effect if `admin.dbcleanup.device.maxSessionsToKeep` is set | From `0` to `MAXINT` | `100` | ::: ### Instance configuration The instance configuration is controlled using a file called `encap-instance.properties` within the `/core/config` directory in your Encap server distribution. The file defines parameters that are used by the startup script. The properties and their function are described in the tables below. The properties have default values which are left commented out in the provided configuration file. You only need the set the values that differs from the default value in the configuration file. #### Bind address and port :::CustomTable{columnWidths="25% 50% 25%"} | **Property name** | **Description** | **Default Value** | | :-- | :-- | :-- | | `jetty.host` | IP address or hostname the server binds to. When using the default value of `0.0.0.0`, Jetty server listens on all local interfaces. It is highly recommended to set it either as a host name or IP address to identify a specific network interface on which to listen. If you decide to install a reverse proxy, make sure that this interface is shielded from the outside world by reliable firewall rules. Only the reverse proxy should be allowed access to the web server. If you decide to use the web server directly, make sure that you bind it on a public- facing interface and your firewall rules expose the web server's HTTP and HTTPS ports to the outside world. Ideally, your firewall should filter all other ports. `${HOSTNAME}` as value is no longer supported since version 3.10. | `0.0.0.0` | | `jetty.http.port` | Listening port for HTTP connections. If you decide to install a reverse proxy, this is the port that your proxy server will be delegating HTTP requests to. If you decide to use the web server directly, you should change this value to `80`, the standard HTTP port. | `9080` | | `jetty.ssl.port` | Listening port for HTTPS connections. If you decide to install a reverse proxy, this is the port that your proxy server will be delegating HTTPS requests to. If you decide to use the web server directly, you should change this value to `443`, the standard HTTPS port. | `9443` | ::: #### Scaling :::CustomTable{columnWidths="25% 50% 25%"} | **Property name** | **Description** | **Default Value** | | :-- | :-- | :-- | | `java.vm.options` | To control minimum/starting heap size and max heap size. This should be scaled based on the number of max concurrent sessions but not exceed physical memory on server. | `-Xms512M -Xmx2G` | | `jetty.threads.max` | Max number of concurrently processed threads (Jetty is set up with a non-blocking threading model so only connections with request processing is using a thread). | `100` | ::: #### Log and runtime mode :::CustomTable{columnWidths="25% 50% 25%"} | **Property name** | **Description** | **Default Value** | | :-- | :-- | :-- | | `encap.mode` | Encap server runtime mode. Enforces stricter checks and limits error messages passed to clients when `DEPLOYMENT` is used. Use `DEPLOYMENT` for production. | `DEPLOYMENT` | | `request.log.format` | Default format of request log. More details about the format: [Extended Log File Format](https://www.w3.org/TR/WD-logfile.html) | `%{client}a - %u "%r" %s %O "%{Referer}i" "%{User-Agent}i"` | ::: #### Public location configuration :::CustomTable{columnWidths="50% 25% 25%"} | **Property name** | **Description** | **Default Value** | | :-- | :-- | :-- | | `publicPath` | This acts as a prefix for the context paths of Encap server web applications. If you decide to install a reverse proxy, this parameter can be used to perform path-based mapping from a virtual server configuration in your proxy server to the Encap server. Whether you use a reverse proxy or let your users access the web server directly, this parameter should be set to the path where users will access the Encap server web applications. If you do not need path-based mapping and want to install the Encap server web applications on the domain's root, the value of this parameter should be blank. | `` | ::: #### TLS configuration The supported protocols, ciphers and security mechanisms used are chosen based on recommendations from [ssllabs.com](http://ssllabs.com/), [owasp.org](http://owasp.org/) and [nist.gov](http://nist.gov/). If TLS is used for communication with the Encap server update the following properties to configure your SSL setup. :::CustomTable{columnWidths="25% 50% 25%"} | **Property name** | **Description** | **Default Value** | | :-- | :-- | :-- | | `jetty.keystore` | SSL keystore filename (residing on class-path `/core/config/`). | `ssl.jks` | | `jetty.keystore.pw` | Keystore password | Secret | | `jetty.keyManager.pw` | Private key password | Secret | | `jetty.truststore` | SSL truststore filename. Default is same as keystore (residing on class-path `/core/config/`). | `ssl.jks` | | `jetty.truststore.pw` | Truststore password (default is to use same file and hence same as keystore password) | Secret | ::: ##### Supported protocols and ciphers The Encap server has support for TLS 1.2 and TLS 1.3. The number of devices not supporting TLS 1.2+ is limited. **Example: Supported ciphers** ``` TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 ``` ##### HTTP Strict Transport Security HTTP Strict Transport Security (HSTS) is a web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking. At first connection with the server, the user agent is sent an HTTP response header `Strict-Transport-Security`, and, when enabled, the user will be unable to connect to the website without a secure connection. ## Encap concepts and configuration ### Generate API keys for REST authentication Encap server requires an API key for authenticating against the REST API. An API key consists of a key/secret pair. The recommended way is to generate it through the REST API, but the first ADMIN-level API key has to be generated using the script. #### REST API The REST API is the preferred way to manage API keys. There exists two APIs for managing API keys: - [The standard REST API](https://demo.encapsecurity.com/pt/api/docs/index.html#_api_key); can create and manage keys for the organisation the user belongs to. - [The admin REST API](https://demo.encapsecurity.com/pt/admin-api/docs/index.html#_api_key); can create and manage keys for any organization. Requires an ADMIN user for accessing. #### Manage API key script The script is only intended for creating the first ADMIN API key. `core/scripts/manageApiKey.sh` manages API keys. Type `./manageApiKey.sh help` to see flags and configuration. ### Setting up end-to-End encryption between device client and Encap server The Encap server uses end-to-end encryption (E2EE) to secure communication between device clients and the server. The Encap client encrypts all communication using a public E2EE key from the Encap server that belongs to an application configuration. :::warning Important Applications built with Encap SDK **3.22** or later use E2EE protocol V4, which is based on X25519 (Curve25519) for key exchange and AES-GCM for encryption. These applications require an X25519 E2EE key to communicate with the server. The SECT233K1 key algorithm is for legacy clients. If you still have applications built with SDK versions earlier than 3.22 in production, you should keep the SECT233K1 key enabled until all clients have been upgraded. ::: In a scenario where the private and public key of the Encap server needs replacement, the Encap server supports multiple private and public keys per application configuration for this purpose. The server can continue to support the old Encap client application even if new keys have been generated for the application configuration. A default E2E key is configured on the Encap server during installation. The default key pair is intended for testing only as this is shared by all Encap customers. You can find out how to generate a new key pair and configure the server with it the sections below. #### Managing E2E keys using the REST API E2E keys can be created and managed using the REST API. Please see the [End-to-End Key API](https://demo.encapsecurity.com/pt/api/docs/index.html#_end_to_end_key) documentation for details. For applications built with Encap SDK **3.22** or later, create the key with `algorithm` set to `X25519`: ```json title="Example: Key creation using X25519" { "name": "app-e2e-x25519", "description": "E2E key for SDK 3.22 app builds", "algorithm": "X25519" } ``` If `algorithm` is omitted, the REST API creates a legacy `SECT233K1` key for backward compatibility with older clients. #### Configure the device client with the new key pair Use the returned public key in the SDK configuration for the upgraded app. :::warning Important You should keep existing legacy `SECT233K1` keys enabled until older app versions are no longer used. ::: ### Manage keys and certificates All keys and certificates are handled by the REST API. Description of the various keys/certificates that exist: - The E2E key used on the Encap server for end-to-end encryption between the client and server. - The APNs push certificate and private key used for sending APNs push for an application configuration, a PKCS12 keystore containing both entities. You can find out how to create these on the [APNs certificates and tokens](/docs/mobile-identity/encap/server/apns-certificates-and-tokens.mdx) page. - The APNs token used for sending APNs push, an authentication token signing key provided by Apple. You can find out how to create these on the [APNs certificates and tokens](/docs/mobile-identity/encap/server/apns-certificates-and-tokens.mdx) page. #### REST APIs Keys and certificates are managed using the REST API. - [End-to-End Key API](https://demo.encapsecurity.com/pt/api/docs/index.html#_end_to_end_key) - [APNs certificate API](https://demo.encapsecurity.com/pt/api/docs/index.html#_apns_certificate) - [APNs provider token API](https://demo.encapsecurity.com/pt/api/docs/index.html#_apns_provider_token) ### Manage application configurations #### Configuring APNS (Apple Push Notification Service) Encap supports both APNS certificates and APNS Tokens and are managed in the REST APIs. The APNS certificate or token needs to be added before it can used in an application configuration. If push is enabled in the application configuration, then it is required to specify the APNS certificate or token when adding the application configuration. It is also possible to update the APNS certificate or token for an application configuration. :::tip Note Changes to the application configuration, for example to APNs certificates, will be updated in runtime. This means that they do not require a server restart. ::: #### Known limitations for application configurations If an application configuration is created and then removed, it is not possible to add a new application configuration with the same application ID. #### REST API Application configurations are managed using the REST API. See the [App Config REST API docs](https://demo.encapsecurity.com/pt/api/docs/index.html#_application_configuration) for more details. ### Manage organisations An organisation is a top level concept owning resources in Encap. There are two types of organisations, **Standard** and **Admin**. A **Standard** organisation owns application configurations, API Keys, APNS certificates and E2E keys. There can be multiple standard organisations, and a standard organisation only has access to resources that belongs to that organisation. :::tip Example When starting an authentication through the REST APIs using an API key, the server will only start an authentication if the API key and the specified `AppConfig` in the request belongs to the same organisation. This adds a layer of authorisation on the REST APIs, only allowing API Keys to perform requests on resources that belong to the same organisation. ::: An **Admin** organisation owns resources that are shared server-wide. There can only be one admin organisation, and it is created when initialising or upgrading the database. #### REST API The admin REST API is the preferred way of managing organisations. See the [Organization REST API](https://demo.encapsecurity.com/pt/admin-api/docs/index.html#_organization) docs for more details. #### Using script (deprecated) Managing organisations using script is deprecated. `core/scripts/manageOrganization.sh` manages organisations. Type `./manageOrganization.sh help` to see flags and configuration. Diagram showing organisation management --- ## Server maintenance ## Logs All logs are found in `/core/logs`. Logs are rotated daily and logs older than the history limit for the specific log type are deleted permanently from the file system. If you wish to keep all logs for archival purposes, you must move old logs out of the Encap server log folder. This can be done when the Encap server has rolled the logs of the current day and the server has started writing the logs of the next day, or at any point after this. You can find further information about log configuration, log types, and available metrics on the [Encap server logs](/docs/mobile-identity/encap/server/manual/encap-server-logs.mdx) page. ## Database cleanup In order to reduce the database size, and to speed up backup procedures and Encap upgrades, it can be advantageous to regularly remove data that is no longer required. To facilitate this, the Encap server provides an optional database cleanup service as part of the Encap server. This is enabled by default. You can find out how to configure this in the next section. ### Removal of information The cleanup job removes information related to registrations, sessions and audits. During normal operation, the Encap server stores session information for each operation and an audit trail in the database. This information is used by the reporting service and for auditing purposes, but is not necessary for authentication purposes once the session has expired and the session, and all the session related data, will be removed by the cleanup job. During deletion of a registration, the Encap server tombstones the registration so it can no longer be used and is therefore no longer required. The cleanup job will remove all deleted registrations, and all the data related to the registrations, and the audit trail. Below is a high level diagram of Encap's data model, the boxes marked in green are cleaned during the cleanup job. Diagram showing database cleanup model ### Database cleanup configuration The cleanup service is configured in `encap-cluster.properties`. See the [Server configuration](/docs/mobile-identity/encap/server/manual/server-configuration.mdx) page for information on how to configure. The result of each cleanup run can be seen in the Encap REST APIs. ## Regular maintenance Recommended regular maintenance. ### Daily **Log rotation** - Proxy (dependent on proxy setup) - Encap server: - `/core/logs` - Handled by the server itself. :::info Want to learn more? For more information, see the [Encap server logs](/docs/mobile-identity/encap/server/manual/encap-server-logs.mdx) page. ::: - Database **Backup** - Database - Encap server and proxy server configuration. - Encap server and proxy server logs (if deemed necessary from a security standpoint, the logs are not necessary to restore an Encap server installation). Archive old Encap server and proxy logs. The age at which the logs should be archived is up to operations. ### Weekly None. ### Monthly None. ### At certificate expiry An Encap server environment contains several certificates all with a set expiry date. It is necessary to renew and install certificates well in advance of the expiry dates. - SSL certificate on proxy (dependant on proxy installation). - Validity dependent on provider. - SSL certificate on Encap server (`/core/config/ssl.jks`). - Validity dependent on provider. - Not used if https is terminated on proxy. - WS and SAML signing key on Encap server (configured in `manageKey.sh` shell script). - Validity dependent on provider. - Apple APNs certificate on Encap server (configured using the REST API). - Valid one year. - Not used if push is not used. ## Monitoring The Encap server can be deployed in a huge amount of different environments and configurations. The following offers basic recommendations for monitoring an Encap server installation and its dependencies. ### Network (ping, telnet... ) Monitor all network connections used by Encap server. If any of these go down Encap server will not work as expected. - Proxy to Encap server. - Encap server to database server. - Encap server to Android Push (if push is used). - `fcm.googleapis.com:443` - `oauth2.googleapis.com:443` for access token - Encap server to Apple (if push is used). - `api.push.apple.com:443` (PRODUCTION) - `api.sandbox.push.apple.com:443` (SANDBOX) - Internet to proxy. - Service provider to Encap server (REST API). - Encap server to service provider (if REST-callback is used). ### Disk status Monitor disk status to ensure necessary mounts are available and have free space on these servers - Proxy server - Encap server - Database server ### JVM on Encap server Monitor basic JVM health parameters. These need to be monitored by a local agent as remote JMX access has been disabled for security reasons. Primary parameters to monitor is: - Heap use not exceeding 90% across GC boundaries. This indicates the application is about to go out of memory, and will usually be accompanied by frequent GC and high GC CPU usage. - JVM CPU use not using 90% or more of total for extended time, peaks are OK. ### CPU (OS) Monitor CPU usage all servers involved to detect high load problems that can lead to slow response times. ### Database Exactly what to monitor on the database is dependent on which database and version is used on the respective installation. Our general recommendations involves monitoring the following parameters: - Free space if not auto extend. If the database goes full Encap server will fail. - Connections in use - Memory in use ### URL (GET) Regularly polling the below URL can give a good basic indication if Encap server is up and running. This does a basic health check of the Encap server. ``` /api/admin/v1/status ``` ### Logs No messages with log level `WARN`, `ERROR` or `FATAL` in `/core/logs/stderrout.log`. For information on file and statsD logging, see the [Encap server logs](/docs/mobile-identity/encap/server/manual/encap-server-logs.mdx) page. ### Device statistics The Encap server supports extracting information about which versions the end customer devices are using. This is explained more in depth in the API documentation: `/api/docs/index.html#_statistics_api`. ## Troubleshooting This chapter lists some known error conditions, and suggested resolutions. ### Too many open files (Soap fault: can't trust X509Certificate chain in WS-Security header) The following error messages in the log may indicate that the server has reached the limit of open files: ``` 2012-09-27 04:03:41,952 ERROR [JIoEndpoint] Socket accept failed: java.net.SocketException: Too many open files : 2012-09-27 04:03:41,988 ERROR |-[net.link.util.config.DefaultConfigFactory] While loading config from: vfs:/home/qa2/installs/latest-snapshot/core/config/encap-cluster.properties java.io.FileNotFoundException: /home/qa2/installs/latest-snapshot/core/config/encap-cluster.properties (Too many open files) : 2012-09-27 04:03:42,060 WARN |-[net.link.util.ws.security.SOAPUtils] Soap fault: can't trust X509Certificate chain in WS-Security header ``` This can be solved by increasing the number of open files, to a value that does not cause too many open files under the desired load. Typically, this involves using `ulimit -n` to monitor the number of open files during load and editing `/etc/security/limits.conf` to change the open files limit. **Example: Set the limit of open files to 8192 for user named `encapuser` on Ubuntu server** 1. In file `/etc/security/limits.conf`: ``` encapuser soft nofile 8192 encapuser hard nofile 8192 ``` 2. Uncommenting `/etc/pam.d/su`: ``` session required pam_limits.so ``` 3. Verifying the number of open files, logout/login to effectuate the configuration changes above: ``` encapuser@encapserver:~$ ulimit -n 8192 ``` ### No MAC address available on server During startup encap server will try to fetch the MAC address of the provided server in encap-instance.properties, if there is no MAC address fallback method will fetch first network interface with a MAC address. If there is no network interface with a MAC address the server will print the following error and exit. ``` ERROR n.e.s.m.audit.AuditContextFilter - No MAC found for this server! System will exit. ``` This can be solved by assuring that a network interface for the server has an MAC address. --- ## Example Postman collection ## Service provider REST APIs You can use these REST APIs to manage and perform operations for resources belonging to a specific organisation. ### Prerequisites - You need an API key ID and secret, that belong to a standard organisation. - To generate on a local server, see the [Generate API keys for REST authentication](/docs/mobile-identity/encap/server/manual/server-configuration.mdx#generate-api-keys-for-rest-authentication) section on the **Server configuration** page to generate an API key. - Download and install the latest version of [Postman](https://www.getpostman.com/). - Download the example Postman collection and environment for Encap SCA, using the buttons below: [**Download Postman collection**](/uploaded-media/mobile-identity/encap/server/encap-3-22-example-postman-collection.json)   [**Download Postman environment**](/uploaded-media/mobile-identity/encap/server/encap-example-pt-postman-environment.json) ### Setup 1. Import the collection and environment. To do this, drag-and-drop. 2. Configure the environment. To do this, click on the settings icon in the top-right corner. 1. Update the `service_url` if needed. The default is the Encap public test environment (PT). 2. Set up Basic Authentication by adding your `key_id` and `key_secret`. 3. Set the `application_id`, which is used in start enrolment. ### API reference documentation * [**API reference**](https://demo.encapsecurity.com/pt/api/docs/index.html): Explore endpoints and properties with example requests and responses ## Encap server administrator REST APIs You can use these REST APIs to manage resources that are shared across all organisations. ### Prerequisites - You need an API key ID and secret, that belong to an admin organisation. - See the [Generate API keys for REST authentication](/docs/mobile-identity/encap/server/manual/server-configuration.mdx#generate-api-keys-for-rest-authentication) section on the **Server configuration** page to generate an API key. - Download and install the latest version of [Postman](https://www.getpostman.com/). - Download the example Postman collection and environment for Encap SCA, using the buttons below: [**Download Postman collection (server admin)**](/uploaded-media/mobile-identity/encap/server/encap-3-22-example-server-admin-postman-collection.json)   [**Download Postman environment**](/uploaded-media/mobile-identity/encap/server/encap-example-pt-postman-environment.json) ### Setup 1. Import the collection and environment. To do this, drag-and-drop. 2. Configure the environment. To do this, click on the settings icon in the top-right corner. 1. Update the `service_url` if needed. The default is the Encap public test environment (PT). 2. Set up Basic Authentication by adding your `key_id` and `key_secret`. ### API reference documentation * [**API reference**](https://demo.encapsecurity.com/pt/api/docs/index.html): Explore endpoints and properties with example requests and responses --- ## REST API guide ## Introduction The Encap REST API is used to integrate client systems with the Encap server in order to perform mobile authentication of customers with designated mobile applications that integrate the Encap mobile authentication API. Operations provided by the API are divided into two categories: - **Service provider API**: This supports actions for enrolments, authentications, device management, application management and statistics. - **Admin API**: This supports server administrators that should have full access to the Encap server and manage resources that are shared between organisations. ## Documentation ### Service provider API documentation The Encap REST API documentation is available as part of the distribution on a running Encap instance. To find this, go to the URL `/api/docs/index.html`. You can also look at the documentation for the latest Encap release on our [public test server](https://demo.encapsecurity.com/pt/api/docs/index.html). ### Admin API documentation The Encap Admin REST API documentation is available as part of the distribution on a running Encap instance. To find this, go to the URL `/admin-api/docs/index.html`. You can also look at the documentation for the latest Encap release on our [public test server](https://demo.encapsecurity.com/pt/admin-api/docs/index.html). ## Suppress event callbacks for device operations Some device management operations can trigger event callbacks when the application configuration subscribes to the relevant event. You can suppress the event callback for a single REST operation by adding the optional query parameter `suppressEventCallback=true`. By default, `suppressEventCallback` is `false`, so existing integrations continue to receive event callbacks. This parameter only affects event callbacks for the REST operation where it is set. It does not affect on-demand callbacks for activation or authentication sessions. The parameter is supported by the following service provider API endpoints: | **Operation** | **Endpoint** | **Suppressed event callback** | | :-- | :-- | :-- | | Lock device | `POST /api/smart-device/v1/devices/{deviceId}/lock` | `DEVICE_LOCKED` | | Unlock device | `DELETE /api/smart-device/v1/devices/{deviceId}/lock` | `DEVICE_UNLOCKED` | | Deactivate device | `DELETE /api/smart-device/v1/devices/{deviceId}` | `DEVICE_DEACTIVATED` | | Lock registrations by device hash | `POST /api/smart-device/v1/devices/deviceHashes/{deviceHash}/lock` | `DEVICE_LOCKED` for each locked registration | ## Getting started Authentication for REST API calls is to handled using Basic Authentication. :::tip Note This authentication is not the same as the authentication service. ::: - All requests are required to have an authorisation header containing a Basic Authentication string. - The Basic Authentication should have the API key ID as the username, and the API key secret as password. - API key provisioning is handled by the Encap server administrator. To learn how to set up the authentications keys, see the [Generate API keys for REST authentication](/docs/mobile-identity/encap/server/manual/server-configuration.mdx#generate-api-keys-for-rest-authentication) section on our **Server configuration** page. * [**Example Postman collection**](/docs/mobile-identity/encap/server/rest-api-guide/example-postman-collection): Explore our example Postman collection --- ## Scaling ## Performance The performance of the Encap server depends on many factors. Different Encap configurations have different performance characteristics, therefore we recommend performance testing each implementation. This page provides guidelines for tuning common Encap use cases. ### Infrastructure #### Higher availability :::tip Note This is a generic example of infrastructure. It does not show setup specifics such as a load balancer heartbeat and shared IP. Depending on the specific solution, the choice details may vary. ::: Diagram showing example of basic infrastructure for higher availability #### Higher peak loads Diagram showing example of horizontally scaling the infrastructure for higher peak loads ### Encap server #### Hardware Usually, the limiting resource on the Encap server is CPU. When selecting Encap server hardware, you should prioritise CPU, then memory. You should ensure that you always have enough physical memory to get the entire Encap process in memory without swapping. As the Encap server runs in a JVM, the max size of the Encap process can be roughly estimated as `JAVA_MAX_HEAP` (see below) + 500 MB. The network bandwidth between the server and the database should be high, as Encap reads and writes a significant amount of data during high load. #### OS On most Linux versions, the default open files limit is too low for larger Encap installation. Since the cost of increasing this limit is very low, we recommend setting it relatively high; at least double the expected number of concurrent connections. In RedHat, this is done in `limits.conf`. ``` sudo vim /etc/security/limits.conf ... soft nofile 65535 hard nofile 65535 ... ``` #### Encap software tuning You can tune for stable performance at high load by: - Limiting the database connections to what the database can handle. - Limiting jetty threads to ensure predictable degradation. - Limiting the queue to ensure fail fast when beyond load acceptance. 1. Database cleanup should be enabled and configured properly. Keeping a large set of outdated data could hurt performance significantly. - The default settings should be tuned to only keep the least possible amount of required data. By default, it is set to 10 years to ensure legal obligations are met. - The cleanup should also be scheduled and ordered to run when the server load is expected to be low. This is typically at night. - If your legal obligations permit, the value of `admin.dbCleanup.daysToKeep` in `encap-cluster.properties` should ideally be set to between 10-31 days. 2. Java heap size is set by using the `java.vm.options` configuration parameter in `encap-instance.properties`. 1. Set maximum Java heap size by changing `-Xmx2G` to correspond to 80% of available physical memory on the server (assuming it only runs Encap), or at least 10 MB x `jetty.threads.max` + 1GB 2. Set minimum Java heap size by changing the `-Xms512M` to half of what is set for the maximum above. 3. Set `jetty.threads.max` in `encap-instance.properties` to the minimum number needed to fully utilise all available CPU. This is normally in the 50-300 range, depending on the number of server CPU cores. 4. The main database connection pool is configured using `encap.db.maxPoolSize` in `encap-db.properties`. The default is set to 0.5 x `jetty.threads.max`. - There are also two more properties `encap.db.mTrans.mainPoolFactor=0.20` and `encap.db.log.mainPoolFactor=0.25`, which are multiplied by the `encap.db.maxPoolSize` to control the `poolSize` for non-core transaction groups. ### Database #### Hardware The two most common limiting factors for the database in an Encap use case is memory cache and disk write IOPS. #### Database cleanup In order to clean up old sessions, the Encap server runs a cleanup job at a configurable interval default once at night. From a performance perspective, it is important that the retention time is not set too long for systems with high load, as this might hurt the database performance significantly. #### Database upgrade In the case of upgrading the Encap server to a new version, you should be aware that a huge database takes time to upgrade. Therefore, it is important to configure the database cleanup job as mentioned above, so that old outdated data is removed from database before the upgrade job is started. #### Database tuning - You should scale connectors to match the aggregate connector count of all Encap servers. - You should set the buffer to a size that allows all active session date in buffer. With a properly tuned buffer almost the entire IO use of Encap will be disk writes. ##### Database graph examples ###### Good We are within the load capabilities of the database. With constant load on the Encap servers we want to see stable performance from the database. The minor amounts of jitter in the graphs is just telling us we are close to the load limit of the database. Also note how disk writes are at 50 MB while disk read is at less than 1 MB. This is typical for the database use of Encap when the database buffer is properly configured. Graph showing example of being within the load capabilities of the database ###### Bad Lots of jitter in the database graphs. With constant load on the Encap servers this is an indication that the database is being pushed beyond it's load limits. If possible, increase the database resource that is bottlenecking performance. Reducing the number of database connections might also help improve performance, but this is a balancing act between having enough but not to many. Graph showing example of being pushed beyond the load limits of the database ### Scaling Encap supports both vertical and horizontal scaling. Below is some examples taken from our Amazon performance test environments. In all cases the Encap servers are backed by the same Amazon RDS database and load balanced by an EC2 load balancer instance. Thanks to the support for stateless load-balancing across multiple Encap servers, it scales near perfectly with the number of virtual cores in both cases until it hits the database limit in this environment. Because of the simplicity in scaling the Encap server itself, very large Encap installations quickly become a question of scaling the database more than a question of scaling Encap. #### Vertical scaling Scaling by increasing single Encap server resources. Since the Encap server usually is bottlenecked by CPU increasing the computational power of the Encap server is one common way to scale out. When growing the Encap server instance we recommend reconfiguring the following parameters, see above for guidance on what they should be set to. - `encap-instance.properties` - Max and min heap settings for `java.vm.options` - `jetty.threads.max` - `encap-db.properties` - `encap.db.maxPoolSize` ##### Example data :::CustomTable | Server type | # vCPU | Auth/sec | Auth/hour | Avg latency (ms) | Comment | | :-- | :-- | :-- | :-- | :-- | :-- | | `c3.large` | 2 | - | - | 10 000+ | Queue full, unable to complete test. | | `c3.xlarge` | 4 | 79 | 284 400 | 3 100 | CPU bound on Encap server. | | `c3.2xlarge` | 8 | 153 | 550 800 | 1 320 | CPU bound on Encap server. | | `c3.4xlarge` | 16 | 275 | 990 000 | 450 | CPU bound on Encap server. | | `c3.8xlarge` | 32 | 282 | 1 015 200 | 450 | Database bound. | ::: Diagram showing example data for vertical scaling #### Horizontal scaling Scaling by adding additional Encap servers. Since Encap supports stateless load balancing across servers adding a new Encap server is very simple. The only thing to be aware of is that adding additional server increases the number of database connections has to handle and increased parallelism against the database usually lead to reduced database performance. ##### Example data :::tip Note In the example data below, each server is a c3.large server. ::: :::CustomTable | Server type | # vCPU | Auth/sec | Auth/hour | Avg latency (ms) | Comment | | :-- | :-- | :-- | :-- | :-- | :-- | | 1 | 2 | - | - | 10 000+ | Queue full, unable to complete test | | 2 | 4 | 77 | 277 200 | 3 250 | CPU bound on Encap servers | | 3 | 6 | 120 | 547 200 | 2 020 | CPU bound on Encap servers | | 4 | 8 | 142 | 547 200 | 1320 | CPU bound on Encap servers | | 5 | 10 | 188 | 676 800 | 940 | CPU bound on Encap servers | | 6 | 12 | 227 | 817 200 | 680 | CPU bound on Encap servers | | 7 | 14 | 264 | 950 400 | 500 | CPU bound on Encap servers | | 8 | 16 | 288 | 1 036 800 | 420 | CPU bound on Encap servers | | 9 | 18 | 285 | 1 026 000 | 470 | Database bound | ::: Diagram showing example data for horizontal scaling ## Storage Storage use is dependent on multiple factors - Type of operation done (activation, authentication). - Configuration of server. - Context information used. - Device information gathered. - Document to sign when signing is used. The information below is just an indication of what it looks like in a normal case ### Encap server With default log levels the only file of a significant size is the audit log. ``` /core/logs/audit.log ``` :::tip Note This file is rotated daily. ::: #### Size increase The table below illustrates the size increase per 1000 sessions. :::CustomTable{columnWidths="33% 33% 33%"} | Operation/Type | Client only | Web service initiated | | :-- | :-- | :-- | | Activation | 4 MB | 8 MB | | Authentication | 4 MB | 8 MB | | Signing | 6 MB | 10 MB | ::: ### Database Most of the database growth in normal use cases consist of session and audit related information. This is information that has no functional value except for reporting and statistics when the session has expired. An effective way of limiting database growth is to configure the database cleanup job to periodically clean out old session and audit data. The use case will determine how long the data should be kept before it is cleaned out, but we recommend keeping data for at least a couple of months to facilitate customer and solution support. #### Size increase The table below illustrates the size increase per 1000 sessions. :::CustomTable{columnWidths="33% 33% 33%"} | Operation/Type | Client only | Web service initiated | | :-- | :-- | :-- | | Activation | 8 MB | 8 MB | | Authentication | 5 MB | 5 MB | | Signing | Dependent on document size. | Dependent on document size. | ::: --- ## Use cases(Encap) On this page, you can explore some examples of how and where Encap SCA is being used today. ## Examples Encap SCA is built flexibly, to enable you to implement any use case that you might have. For example, you can: - Authenticate an end-user in mobile app scenarios - Authenticate an end-user in web scenarios - Onboard and re-onboard an end-user Encap SCA also supports: - PSD2-compliant payment authorisations - Customer support identifications - 3DS payment authorisations - Consent signatures ## Industries Encap SCA is a tool to drive mobile business. Today, there are millions of end-users who use this technology to perform authentications and authorisations across Europe. It can used in many different industries, such as: - Banking - Wealth management - Insurance - Healthcare - iGaming ### Customer cases You can read about how our customers are using our solutions today in our customer cases: * [**Banking**](https://www.signicat.com/customers/s-pankki): See how S-Pankki has increased customer engagement * [**Wealth management**](https://www.evli.com/en/news/try-the-new-my-evli-mobile): See how Evli has improved user experience and security --- ## API reference In our API references, you can find information about the available endpoints and properties, as well as sample requests and responses. ## ReuseID The ReuseID API is our next-generation API for ReuseID services, representing the future of our ReuseID platform. It offers a broader set of functionalities, including authentication with MobileID and Passkeys. * [**ReuseID API (recommended)**](/apis/reuseid/): Manage identities and carry out authentication operations * [**Admin API**](/apis/mobileid-admin/): Manage and administer your ReuseID account ## MobileID Our MobileID API is our first-generation API for mobile authentication. We will continue to fully support it and it will remain functional for all existing customers, where you can also use it in parallell with the ReuseID API. * [**MobileID API**](/apis/mobileid/): Manage identities and carry out mobile authentication operations ## Which API should I use? For an overview of the differences between the APIs, see the table below: :::CustomTable{columnWidths="25% 75%"} | **API** | **Description** | | :-- | :-- | | **ReuseID API** | Our next-generation API for ReuseID services. It represents the future of our ReuseID platform. It offers a broader set of functionalities, including authentication with MobileID and Passkeys. We recommend this for all customers, so that you can utilise the latest capabilities and improvements. For existing customers, it is possible to use ReuseID and MobileID in parallel. | | **Admin API** | Our admin API for managing and administering your ReuseID account. You can also use it to update configurations for MobileID authentication. Most functionality in this API can also be achieved using the user interface in the [Signicat Dashboard](https://dashboard.signicat.com/). | | **MobileID API** | Our first-generation API for mobile authentication Although we recommend that you use our ReuseID API, we will continue to fully support the MobileID API for all existing customers. | ::: --- ## App security App security enables you to protect your app from various threats and attacks with mechanisms such as app hardening and runtime application self-protection (RASP). It is required when using our Authenticator App, and the security mechanisms can be configured to behave according to the desired security policy. :::info Want to learn more? To learn more, see our [App security](/docs/mobile-identity/mobileid/features/app-security.mdx) feature documentation. ::: ## Promon SHIELD® Our Authenticator App uses Promon SHIELD® for app security. It provides robust protection against unauthorised access and app tampering. In order for us to shield the app for you with Promon SHIELD®, you need to provide us with the application signing key. To learn more about this and what is required when publishing your app, see our guides: * [**Publish to Google Play Store**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/google-play-store): Learn how to publish your Authenticator App to the Google Play Store * [**Publish to Apple App Store**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/apple-app-store): Learn how to publish your Authenticator App to the Google Play Store --- ## Application behaviour You can configure how the app behaves. For example: - What authentication methods are allowed. - The PIN length. To learn about and update your configuration, go to: 1. **Signicat Dashboard** > **Products** > **MobileID** > **Features** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour/). 2. Use the tabs to navigate between different configuration options. Once you have finished making your changes, click the **Save** button. --- ## Branding(Configuration-options) ## About Branding It is possible to customise certain elements of the Authenticator App with your own branding. You can do this by supplying us with the necessary resources for each mobile platform. ## What can you customise? You can customise elements such as: - The name of the app. - The application icon. - The logo on the welcome page and home page. - The colour value for various elements within the app, such as the toolbar, button colour and background colour. - The launch image or splash screen, which is displayed during the launch of the app. - The notification icon. - The help page. Please see sections below for details on each element. ### App name The name of the app, which is used in messages to the end-user. :::info Example Welcome to **Signicat Authenticator** ::: ### App icon The icon of the app. Example of an iOS app icon #### App icon sizes for iOS - 1024 px x 1024 px #### App icon for Android For Android we support adaptive icons. Adaptive icons can display differently depending on the individual device capabilities and user theming. You can read more about adaptive icons in the [Android developer documentation](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive). The adaptive icon must meet the following design requirements: - An adaptive icon must be supplied as two layers, which are preferably vector images: 1. The foreground layer, which is the icon itself. 2. The background layer. Example of an Android adaptive icon :::info What does this mean? This diagram shows an adaptive icon defined using foreground and background layers. The 72 dp x 72 dp safe zone shows where your icon and foreground layers will never be clipped by a shaped mask defined by an OEM. ::: - All layers should be sized at 108 dp x 108 dp. - The foreground layer should be at least 48 dp x 48 dp, and should not exceed the 72 dp x 72 dp safe area. - The background layer should be sized at 108 dp x 108 dp, and can be either: - An image. - A colour, given in a hexadecimal colour code format. For example, **#451621**. - Optionally, a monochrome icon can be provided for supported Android launchers. This allows the app icon to inherit the colour of the end-user's chosen wallpaper and other themes. You can learn how to create and export an adaptive icon for Android using an example template in [Figma's documentation](https://www.figma.com/community/file/1131374111452281708/Android-App-Icons). ### Company logo The logo that is used on the welcome page, the home page, and optionally the launch screen for iOS. To get the best result, we advise that you supply a high-quality version of your company logo with a transparent background. The allowed file format of the supplied logo varies depending on the target platform. See sections below for details. Example of a company logo #### iOS allowed file formats You can supply a high-quality version of your company logo in any of the following formats: - PDF (.pdf) - PNG (.png) :::tip Our recommendation We recommend that you use the PDF file format, as this scales better than PNG files. ::: #### Android recommended file formats You can supply a high-quality version of your company logo as either: - SVG (.svg) - High-resolution image file ### Colour You can specify the colour for certain elements within the app. The colour value needs to be in a hexadecimal colour code format. :::info Example Button colour **#451621**. ::: #### Customisable elements :::CustomTable{columnWidths="25% 75%"} | **Element** | **Description** | | :-- | :-- | | Navigation bar colour | Used for the background in the header of the application. | | Status bar colour | Used for the background in the status bar of the device. **Note**: If not provided, then we will use the same colour as the navigation bar. | | Button colour | Used for all accept buttons. | | Background colour | Used for the background of all pages. | ::: ### Launch screen or splash screen The screen that is displayed when the app is being launched. - For iOS it is called the **launch screen**. - For Android it is called the **splash screen**. To get the best result, we advise that you supply a high-quality version of your icon or image with a transparent background. The allowed file format of the supplied asset varies depending on the target platform. See sections below for details. #### Launch screen for iOS For the launch screen on iOS, we use an image on a background. You can supply your own image, and you can also specify the background colour. Example of an iOS splash screen ##### Customisable elements :::CustomTable{columnWidths="25% 75%"} | **Element** | **Description** | | :-- | :-- | | Image | An image, in high quality, to be used on the launch screen. **Note**: If not provided, then we will use your company logo. | | Background colour | The background colour for the launch screen. This needs to be in a hexadecimal colour code format. | ::: ##### iOS allowed file formats You can supply a high-quality version of your launch image in any of the following formats: - PDF (.pdf) - PNG (.png) :::tip Our recommendation We recommend that you use the PDF file format, as this scales better than PNG files. ::: #### Splash screen for Android For the splash screen on Android, you can choose whether this is customised or not. - For customised splash screens, you can: - Add a custom logo - Specify the background colour - Optionally add a branding logo if required. The branding logo is displayed on the bottom of the screen and has a rectangular aspect ratio. - If no custom icon for the splash screen is provided, then the application icon will be used by default. :::info Want to learn more? To learn more about splash screens, see the [Android developer documentation](https://developer.android.com/develop/ui/views/launch/splash-screen). ::: Example of an Android splash screen ##### Customisable elements :::CustomTable{columnWidths="25% 75%"} | **Element** | **Description** | | :-- | :-- | | Icon | The icon that appears in the centre of the splash screen. This can be animated, and follows the same specifications as the [adaptive icon](#app-icon-for-android). **Note**: If a custom icon is not provided, then the application icon will be used by default. | | Background colour | The background colour for the splash screen. This needs to be in a hexadecimal colour code format. | | Branding logo | The branding logo that appears at the bottom of the splash screen. **Note**: This asset is optional. | ::: ##### Branding logo considerations You should consider the following when choosing a branding logo: - It should be no wider than 200 dp, and no taller than 80 dp. - We advise that you supply it as either an SVG (.svg) or a high-resolution image file. - It should be in a rectangular aspect ratio. Branding logos formatted as squares or circles are likely to be cut off. ### Notification icon The small icon that is displayed in a notification when a push message to start the app arrives. This notification is visible when the app is not already running in the foreground. :::note Notification icons for iOS For iOS, a smaller version of the app icon is used for the notification icon. ::: #### Notification icon sizes for Android You have to supply the notification icon with a transparent background. - 24 px x 24 px (mdpi) - 36 px x 36 px (hdpi) - 48 px x 48 px (xhdpi) - 72 px x 72 px (xxhdpi) - 96 px x 96 px (xxxhdpi) ### Help page Our Authenticator App has support for an optional help page, which can contain useful contact information for your end-users. You can navigate to the help page from either the welcome screen or the menu within the app. This page is only visible if you supply any of the supported help details shown in the table below. #### Help details :::CustomTable{columnWidths="25% 75%"} | **Detail** | **Description** | | :-- | :-- | | Email | An email address that the end-users can reach out to if they need to get in contact with your company. | | Website | A link to your website | | Phone | A phone number that the end-users can reach out to if they need to get in contact with your company. | ::: ### Face authentication The [button colour](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/branding/#customisable-elements) and [company logo](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/branding/#company-logo) that you specify for the Authenticator App is also applied to all screens associated with face authentication. Example of a Signicat branded Authenticator App while performing a face scan It is possible to further customise the appearance of the face authentication screens if required. To do this: 1. See which elements can be customised in the [Customizable Elements](https://dev.facetec.com/ui-customization#customizations-customizable-elements) section of the FaceTec documentation. 2. Share your requirements with us. You can do this in the support ticket used for sharing your assets with us. ### Package name (Android only) :::note Android only This step is only required for the Android version of the Authenticator App. ::: You must create a package name with your app and share it with us, as this will define a unique ID for the app which is required when we create it and when you upload it to the Play Store. It is also required for configuring certain features, such as [push notifications](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/push-notifications/index.mdx). #### Format rules When creating a package name for your app: - You must use the following format: ``` com.encapsecurity.android.standardapp. ``` - The package name (``) must: - Be shorter than 10 characters. - Consist only of lowercase letters. ### iOS certificates (iOS only) :::note iOS only This step is only required for the iOS version of the Authenticator App. ::: Before we can publish your iOS app, you need provide us with the required iOS signing assets and your app's Bundle ID: | **Name** | **Description** | | :-- | :-- | | Distribution Provisioning Profile | This is a (`.mobileprovision`) file that must be created for the App ID that you provide. It must include the required capabilities, for example _Push Notifications, Access Wi-Fi Information if your app requires it_. | | iOS Distribution certificate | This must be exported as a `.p12`, with private key included. | | Team ID | This is your Apple Developer Team ID. | | Bundle ID | This is your app's Bundle Identifier. For example, `com.example.myapp`. | :::warning Important If you change the Bundle ID, App ID capabilities, provisioning profile or certificate after delivery, then you need to provide new assets and restart the publishing process. We recommend that you double-check the values before sending them. ::: To learn how to do this, follow the instructions on the [Publish to Apple App Store](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/apple-app-store.mdx) page. ## Branding checklist You can find a checklist of all branding details that you need to share with us in the table below, in addition to an example of each. :::CustomTable{columnWidths="25% 75%"} | **Branding asset** | **Example** | | :-- | :-- | | Application name | `Signicat Authenticator` | | Application icon | Attach files | | Company logo | Attach file | | Colour | Navigation bar and background colour: `#FFFFFF` Button colour: `#2A0062` | | Launch screen (iOS) | Attach file Background colour: `#2A0062` | | Splash screen (Android) | Attach files for icon and branding logo Background colour: `#2A0062` | | Notification icon | Attach file | | Help page (optional) | Email: `support@example.com` Website: `www.example.com` Phone: `+47 00000000` | | Package name (Android) | `signicorp` | ::: ## Share the assets with us To share the assets with us, you can create a support ticket in the Signicat Dashboard: * [**Share the assets with us**](https://dashboard.signicat.com/contact-us/tickets/new): Create a support ticket in the Signicat Dashboard --- ## Configuration options It is possible for you to configure the look, behaviour and functionality of the Authenticator App to suit the requirements of your business. ## What can you configure? To learn about what you can configure, use the buttons below: * [**App security**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/app-security): Learn how to set up proactive security for the Authenticator App * [**Application behaviour**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/application-behaviour): Learn how to configure the behaviour of the Authenticator App * [**Branding**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/branding): Learn how to customise the Authenticator App with your branding * [**Localisation**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/localisation): Learn about what languages the Authenticator App supports * [**Push notifications**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/push-notifications/): Learn how to set up push notifications for the Authenticator App ## MobileID features You can configure a range of additional MobileID features for the Authenticator App. To learn about what features we offer and how they work, see our MobileID feature guides: * [**MobileID features**](/docs/mobile-identity/mobileid/features/): Learn about MobileID features in our feature guides --- ## Localisation(Configuration-options) You can configure the language of the Authenticator App to suit your requirements. The Authenticator App currently supports the following languages: - English - Norwegian - Swedish - Finnish :::note Language not currently supported? If your desired language is not currently supported but you wish to add it, then you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Create APNs token(Push-notifications) For iOS, we use Apple Push Notification service (APNs) to send push notifications. To be able to use this, you need to create an APNs token for your application: ## 1. Create an APNs provider authentication token 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **Keys**. Next, click the **+** button to register a new key. 4. Add a **Key Name** and optionally a **Key Usage Description**. 5. Tick the **ENABLE** box for **Apple Push Notifications service (APNs)**, then click the **Configure** button. 6. In the **Environment** dropdown menu, select the desired option, then click the **Save** button. 7. Click the **Continue** button, then click the **Register** button. 8. Copy the displayed Key ID (`KeyID`) and store it in a secure place. 9. Click the **Download** button to download `.p8` file containing the token, then store it in a secure place. ## 2. Find your Team ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Membership details**. 2. Copy the **Team ID** and store it in a secure place. ## 3. Find your Bundle ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the application that you are configuring the APNs token for. 4. Copy the **Bundle ID** and store it in a secure place. ## 4. Add to enabled capabilities You need to add push notifications as enabled capabilities for the provisioning profile when you are publishing your app. To do this: 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the App ID that you want to update, then click **Edit**. 4. Select the checkbox to enable push notifications. :::tip Tip You can also enable any other app capabilities that you want to allow, such as time-sensitive notifications. To learn more about this, see the [Time-sensitive notifications](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications/#time-sensitive-notifications) section in our iOS SDK **Push notifications** documentation. ::: 5. Click the **Save** button. :::note Note If a warning dialogue box appears, then click the **Confirm** button to finalise your changes. ::: --- ## Create Firebase project(Push-notifications) For Android, we use Firebase Cloud Messaging (FCM) to send push notifications. To be able to use this, you need to create a Firebase project for your application: ## 1. Create a new Firebase project You need to create a Firebase project so that you can download the push configuration file for the Android platform. To do this: 1. Log in to the [Firebase Console](https://console.firebase.google.com/u/0/) with your Google account. If you do not have one, then you can create a Google account for free. 2. On the Firebase Console home page, click the **Add project** button. 3. Enter a project name. This name should be relevant to your name or business. 4. **Optional**: Choose whether to enable Google Analytics for your project. This is not a requirement, but can be enabled at this point if you want analytics tracking. 5. Click the **Create project** button, then click **Continue**. ## 2. Download the push configuration file You must generate the platform-specific configuration file that links your app to Firebase services. This configuration file is necessary to enable push notifications. To do this: 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **General** tab, then scroll down to the **Your Apps** section. 3. Click the **Add app** button, then select the **Android** platform. 4. Enter your Android app's package name. :::tip Tip You can also add a nickname for the app and specify the SHA-1 if required. The SHA-1 is optional for push notifications, but may be required for other Firebase services. ::: 5. Click the **Register app** button. 6. Download the `google-services.json` configuration file and store it in a secure place. 7. Skip the next steps, then click the **Continue to console** button. ## 3. Create the service account key 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **Service accounts** tab and click the Google Cloud link for **All service accounts**. This will open the Google Cloud Project associated with your Firebase project. 3. In the left-side menu click on **Service Accounts** 4. With Firebase Admin SDK selected, press **Generate new private key**. 5. When the new `.json` key file is downloaded, ensure that you store it in a secure place. --- ## Push notifications(Push-notifications) ## About push notifications Our push notifications feature enables you to inform the end-user that something is happening in your app that requires their attention. This is an optional feature that you can configure in the application configuration. If you enable push, you can also toggle it when initiating the authentication. :::note Note Push notifications can be used to improve the end-user experience, but you are not required to use them. They have no impact on the authentication operation itself. ::: ### Example use cases - You want to notify your end-users who are attempting to log in to your website that they have a login request to approve. - You want to notify your end-user on their mobile device that they have a transaction to authorise. ## How to implement push notifications To implement our push notifications feature for your Authenticator App, you need to: - [Configure the application configuration](#configure-the-application-configuration). - [Share the information with Signicat](#share-the-information-with-us) ### Configure the application configuration To use push notifications, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to receive push notifications. #### Prerequisites Before you start, you need to create an APNs token (iOS) and set up a Firebase project (Android). To learn how to do this, use the buttons below: * [**Android**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/push-notifications/create-firebase-project): Learn how to create a Firebase project for your app * [**iOS**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/push-notifications/create-apns-token): Learn how to create an APNs token for your app #### Configure push notifications Once you have completed the prerequisites, you can configure your app to use push notifications. :::warning Configure Android and iOS simultaneously Currently, you need to configure push notifications for Android and iOS simultaneously. ::: To start, go to **Signicat Dashboard** > **Products** > **MobileID** > **Features** > [**Push**](https://dashboard.signicat.com/mobileid/features/push). ##### 1. Add APNs token You need to add the APNs token using the values obtained when you created it in the Apple Developer Program Portal. To do this: 1. Select the **APN tokens** tab. 2. Click the **+ Add new** button. 3. Add the following values to the fields in the dialogue box: | **Field name** | **Description** | | :-- | :-- | | Name | Give the APNs token a name. | | Description | Give the APNs token a description. | | Key ID | Add the Key ID that you obtained when you created the token. | | Team ID | Add your Team ID that you obtained from **Membership details**. | | Private key | Add the private key from the `.p8` file that you downloaded when you created the token.

**Note**: You can open the `.p8` file using a text editor app. | 4. Click the **Add** button. :::tip Tip An APNs token can be used by all accounts in the same organisation. ::: ##### 2. Enable push notifications You need to enable and configure push notifications in your application configuration. To do this: 1. Select the **Configuration** tab. 2. Use the toggle button to enable push notifications. Once enabled, additional options that you can use to configure push notifications become available. 3. To configure APNs: 1. Select the APNs token that you created. 2. Add the Bundle ID that you obtained from **Identifiers** in the prerequisite step. 4. To configure Firebase, add the contents of the `.json` key file obtained in the prerequisite step to the **Firebase service account** field. 4. Once you have finalised configuring push notifications, click the **Save** button. :::info Want to learn more? To learn more about the configurable properties, see the [Push notifications](/docs/mobile-identity/mobileid/features/application-configuration/#push-notifications) section in our **Application configuration** feature documentation. ::: ### Share the information with us You must also share the following information with us, by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets) in the Signicat Dashboard: - The `google-services.json` configuration file that you downloaded in the prerequisite step. - If you have not already, then you also need to share the Android package name with us as described in the [Branding](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/branding.mdx#package-name-android-only) guide. --- ## Activate/deactivate biometrics The end-user has the option to activate/deactivate biometric authentication methods on devices that support this. ## What does it look like for you end-users? ### Deactivating biometrics You can use the image slider below to see what deactivating biometrics looks like for your end-users. ### Activating biometrics You can use the image slider below to see what activating biometrics looks like for your end-users. --- ## Authentication and authorisation Once you have registered the device and activated authentication credentials, you can then use the app to authenticate and authorise operations for your end-users. All operations are initiated through our [**Start authentication**](pathname:///apis/reuseid/#tag/MobileID-Authentication/operation/addAuthentication) endpoint, then completed by the end-user in the Authenticator App. ## What does it look like for your end-users? You can use the image slider below to see what the authentication operation looks like for your end-users. ## How does the flow work? In this flow there are three important concepts to understand: - [Push notifications](#push-notifications) - [Authentication methods](#authentication-methods) - [Operation context](#operation-context) ### Push notifications MobileID supports sending push notifications to inform the end-user that something is happening that requires their attention in the app. This is an optional feature that you can configure in the [application configuration](/docs/mobile-identity/mobileid/features/application-configuration.mdx). If you enable push, you can also toggle it when [initiating the authentication](pathname:///apis/reuseid/#tag/MobileID-Authentication/operation/addAuthentication). :::note Note Push notifications is a tool to improve the end-user experience, but you are not required to use it. It has no impact on the authentication operation itself. ::: ### Authentication methods The Authenticator App supports two-factor authentication. When [initiating the authentication](pathname:///apis/reuseid/#tag/MobileID-Authentication/operation/addAuthentication), you have the option to specify the authentication method in the request. If you do not specify an authentication method, then the app uses biometrics as the default if it is activated on the end-user's device. If biometrics are not activated, then the app defaults to using a PIN instead. The Authenticator App supports the following authentication methods: - PIN - Biometrics (Face ID, Touch ID, BiometricPrompt) - [Face Authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx) The end-user must have activated the authentication method before it can be used in authentication operations. ### Operation context For each operation, you can set a context. This is a text which is passed to the mobile device. The operation context allows you to send important information to the end-user, through a secure channel with end-to-end encryption (E2EE). This information can be passed: - Before the operation has been approved (pre-operation context). - After the operation has been successfully completed (post-operation context). :::info Want to learn more? For more information, see the [Operation context](/docs/mobile-identity/mobileid/features/operation-context.mdx) page in the MobileID feature documentation. ::: ## Integration flow The sequence diagram below provides an overview of the operations that make up the authentication process with the Authenticator App. ```mermaid sequenceDiagram title MobileID authentication with Authenticator App actor user as End-user participant app as Authenticator App participant sp as Your server participant r as ReuseIDwith MobileID sp->>r: POST /authentications with userId, deviceId and context r-->>sp: OK r->>app: Push notification user->>app: End-user opens Authenticator App app->>r: (SDK call) startAuthentication r-->>app: startAuthentication result app->>user: Displays context to userAsks user to authenticate with PIN or Biometrics user-->>app: Authenticates with PIN or biometrics app->>r: (SDK call) finishAuthentication r-->>app: finishAuthentication result r->>sp: POST /callback with authentication result sp-->>r: OK ``` --- ## Change the PIN Your end-users can change their PIN in the Authenticator App. ## How to change the PIN To change their PIN, your end-users must: 1. Open the Authenticator App, then tap the menu icon in the top-left corner. 2. Tap **Change PIN**. 3. To approve, authenticate using one of the [allowed authentication methods](#allowed-authentication-methods) for changing the PIN. 4. Enter a new PIN. :::note Default authentication method If enabled, then biometric authentication is the default authentication method that the Authenticator App presents to your end-users when they change their PIN. ::: ### Allowed authentication methods You can control what authentication methods are allowed when the end-user activates a new authentication method or changes their PIN. The Authenticator App supports both PIN and biometrics. To configure which of these methods your end-users can use: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > **Features** > **[Application behaviour](https://dashboard.signicat.com/mobileid/features/application-behaviour)**. 2. Select the **Authentication** tab. 3. Under the **Allowed authentication methods when activating new method or changing PIN** section, select the desired authentication methods. 4. To save your changes, click the **Save** button. ## What does it look like for your end-users? You can use the image slider below to see what changing the PIN looks like for your end-users. --- ## Deactivate The end-user has the option to deactivate the app and delete the activation data from the device. :::warning This operation can not be reverted This operation can not reverted. To get access to the app again, the end-user must perform a new registration. ::: ## What does it look like for your end-users? You can use the image slider below to see what deactivating the account looks like for your end-users. --- ## How it works(How-it-works) ## Process flows The Authenticator App implements two key process flows: - Registering the device and activating authentication credentials. - Performing authentications and authorisations. To learn about how these flows work and what they look like, see our documentation using the buttons below: * [**Registration**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/registration): Learn how to register the device and activate authentication credentials * [**Authentication**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/authentication-authorisation): Learn how to use the app to authenticate and authorise operations for your end-users ## Additional flows There are additional flows that are available once the Authenticator App is activated, such as changing the PIN or deactivating the account. To learn about how these flows work and what they look like, see our documentation using the buttons below: * [**Activate/deactivate biometrics**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/activate-deactivate-biometrics): Learn how to activate and deactivate biometrics * [**Change PIN**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/change-pin): Learn how to change the PIN * [**Deactivate account**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/deactivate-account): Learn how to deactivate the account --- ## Registration Before you can use the app for authentications and authorisations your end-users need to register the device and activate authentication credentials. :::note Onboard with ID document and biometric verification It is also possible to onboard and register the app with ID document and biometric verification using our ReuseID onboarding APIs. To learn how to do this, see our ReuseID onboarding [Quick start guide](/docs/reuseid/quick-start-guides/identity-proofing.mdx). ::: ## What does it look like for your end-users? You can use the image slider below to see what the registration operation looks like for your end-users. ## How does the flow work? In this flow there are three important concepts to understand: - [Activation code](#activation-code) - [Authentication methods](#authentication-methods) - [Operation context](#operation-context) ### Activation code The app is activated with an activation code. The activation code is generated by MobileID and passed to you in the response when you [initiate a registration](pathname:///apis/reuseid/#tag/MobileID-Registration/operation/addRegistration). It is your responsibility to display the activation code to the user in the preferred channel; for example, this could be a web page after the user has authenticated themselves. #### QR code The app has built-in support for scanning a QR code to retrieve the activation code. - This provides a better user experience for the end-user, as they can scan the code instead of entering it manually. - This makes it easier for you to use longer and more secure activation codes. To use this, you must generate a QR code and display it to the end-user. The end-user can then scan the QR code with the camera on the device. ### Authentication methods Once the activation code has been successfully verified the end-user will activate authentication methods. The Authenticator App supports the following authentication methods: - PIN - Biometrics (Face ID, Touch ID, BiometricPrompt) - [Face Authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx) When using the Authenticator App it is required for the end-user to select a PIN. If biometrics are supported in the [application configuration](/docs/mobile-identity/mobileid/features/application-configuration.mdx), then the end-user will be asked during the registration if they want to activate biometrics. All methods can be managed (update, enable, disable) by the end-user in the menu in the app. ### Operation context You can set a post-operation context when using the [**Start registration**](pathname:///apis/reuseid/#tag/MobileID-Registration/operation/addRegistration) endpoint. The post-operation context is passed to the Authenticator App, through a secure channel with end-to-end encryption (E2EE), after a successful registration. Allowing you to pass data in a secure way to your end-user once they have completed the registration. :::info Want to learn more? For more information on operation context, see our [MobileID feature documentation](/docs/mobile-identity/mobileid/features/operation-context.mdx). ::: ## Integration flow The sequence diagram below provides an overview of the operations that make up the registration process with the Authenticator App. ```mermaid sequenceDiagram title MobileID registration with Authenticator App actor user as End-user participant app as Authenticator App participant sp as Your server participant r as ReuseIDwith MobileID Note over user, r: Activate PIN sp->>r: POST /registrations with userId r-->>sp: Activation code Note over user, sp: You display activation code to end-user user->>app: Opens Authenticator AppEnters/scans activation code app->>r: (SDK call) startActivation with activation code r-->>app: startActivation result app->>user: Ask end-user for PIN user-->>app: End-user selects PIN app->>r: (SDK call) finishActivation r-->>app: finishActivation result r->>sp: POST /callback with registration result sp-->>r: OK Note over user, r: Activate biometrics app->>user: Ask end-user if they want to activate biometrics user-->>app: Yes! app->>r: (SDK call) startAddOrUpdate r-->>app: startAddOrUpdate result app->>r: (SDK call) finishAddOrUpdate r-->>app: finishAddOrUpdate result ``` --- ## Authenticator App(Authenticator-app) ## About the Authenticator App The Authenticator App is a robust, white-labelled solution designed to deliver secure and seamless two-factor authentication (2FA) for a wide range of digital interactions. It enables your end-users to securely authenticate using their mobile device as a possession element, combined with either biometrics or a PIN; this ensures strong customer authentication. It is ideal for any scenario where secure user verification is essential, for example: - Logging into a service. - Authorising a transaction. - Confirming a sensitive operation. The app is customisable, which allows you to tailor it to your brand identity whilst leveraging Signicat's powerful MobileID authentication capabilities. This means that you can provide your end-users with a smooth, user-friendly experience that meets the highest security standards and regulatory requirements. :::note Already have your own app? If you already have your own app, then we recommend that you use either our Android or iOS SDK to get the most out of this product. ::: ### Supported operating systems The Authenticator App supports the following operating systems: - Android 9.0 and later. - iOS 15.0 and later. ### What does it look like? You can see what the Authenticator App looks like and how it can be used in our [YouTube videos](https://youtube.com/playlist?list=PLdQcZnykKdPOKpyDH4vxiqUbgq0NhMSf-). These videos demonstrate the Authenticator App being used in our demo bank (West Springfield Bank). ## Try it out You can use our quick start guide to get a test version of the Authenticator App and try it out. * [**Quick start guide**](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication): Try out the Authenticator App using Postman or similar tools ## Learn more * [**How it works**](/docs/mobile-identity/mobileid/authenticator-app/how-it-works/): Explore different flows to learn how the Authenticator App works * [**Configuration options**](/docs/mobile-identity/mobileid/authenticator-app/configuration-options/): Learn how to configure the Authenticator App to your requirements * [**Publish the app**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/): Learn how to publish the app on the Apple App Store and Google Play Store --- ## Publish to Apple App Store ## Overview In this guide, you can learn about how you can publish your app on the App Store. To do this, you need to undertake the following: - Generate the iOS distribution certificate (`certificate.p12` file). - Generate a new Distribution Provisioning Profile (`.mobileprovision` file) for App Store in the Apple Developer Portal. - Securely share these certificates, your Bundle ID and your Team ID with Signicat. ## How to publish your app ### 1. Generate an iOS distribution certificate To generate an iOS distribution certificate (`certificate.p12` file): 1. In the Apple Developer portal, navigate to the **Certificates, IDs and Profiles** section, then click **Certificates**. 2. On the **Certificates** page, click the circular **+** (add) button. 3. Under the **Software** section, select **Developer ID**, then click the **Continue** button. 4. You now need to create a certificate signing request (CSR). To do this: 1. Launch **Keychain Access** located in `/Applications/Utilities`. 2. From the top toolbar, click **Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority**. This will open the Certificate Assistant dialogue. 3. In the **User Email Address** field, enter an email address. 4. In the **Common Name** field, enter a name for the key. For example, `Gita Kumar Dev Key`. 5. Leave the **CA Email Address** field empty. 6. In the **Request is:** section, select **Saved to disk**, then click the **Continue** button. 5. Return to the **Create a new certificate** page in the Apple Developer portal, then click **Choose File**. 6. In the dialogue that appears, select the certificate request file, then click **Upload**. :::tip What does this look like? This file will have a `.certSigningRequest` file extension. ::: 7. Click the **Continue** button. 8. Click the **Download** button. 9. Double-click it to add it to your Keychain. 10. In Keychain Access, find your new certificate. Right-click it, then click **Export**. 11. In the save dialog, choose `.p12` as the file format. Set a password when you save. ### 2. Create an App ID To create an App ID: 1. Go to the Apple Developer Portal. 2. In the left-side menu, select **Identifiers**. 3. Click the **+** (add) button. 4. Select **App IDs**, then click **Continue**. 5. Choose **App** as the type, then click **Continue** again. 6. Complete the following fields: - **Description**: For example, your app name. - **Bundle ID**: For example `com.company.appname`. This must match your Xcode project's Bundle Identifier. 7. Under **Capabilities**, ensure that you enable the following: - Access Wi-Fi Information - Push Notifications 8. Click **Continue**, then **Register**. ### 3. Create a Distribution Provisioning Profile To create a Distribution Provisioning Profile (`.mobileprovision` file) for App Store Connect distribution: 1. In the Apple Developer portal, navigate to the **Certificates, IDs and Profiles** section, then click **Profiles**. 2. On the **Profiles** page, click the circular **+** (add) button. 3. Under the **Development** section, select the type of provisioning profile that you want to create, then click the **Continue** button. 4. Using the dropdown menu, select the App ID that you want to use for development, then click the **Continue** button. 5. Using the radio buttons, select one or more development certificates, then click the **Continue** button. 6. Select one or more devices, then click the **Continue** button. 7. In the **Provisioning Profile Name** field, enter a profile name, then click the **Generate** button. 8. Click the **Download** button. :::info Want to learn more? To learn more about these steps, you can refer to the Apple developer documentation: - [Create a development provisioning profile](https://developer.apple.com/help/account/manage-profiles/create-a-development-provisioning-profile/) - [Certificates overview](https://developer.apple.com/help/account/create-certificates/certificates-overview) - [Create a certificate signing request](https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request) ::: ### 4. Send the certificates to Signicat Next, you need to securely share the Distribution Provisioning Profile (`.mobileprovision` file), iOS distribution certificate (`certificate.p12` file), your Team ID and your Bundle ID with Signicat. To do this: 1. In the Signicat Dashboard, navigate to the [Contact Us](https://dashboard.signicat.com/contact-us/tickets) service. 2. Create a new support ticket, where you share the following files from **Step 1** and **Step 3**: - `certificate.p12` file - `.mobileprovision` file 3. Add your Team ID, Bundle ID and `certificate.p12` file password to the support ticket. ### 5. Shield and distribute :::note Note These steps are undertaken by Signicat. This means that they do not require any action from you. ::: 1. Once we have received your support ticket, we will build the app with your certificates. 2. We will shield the app. 3. We will distribute the app to you by uploading it to our Nexus repository. ### 6. Upload the shielded app You need to upload the shielded app. To do this for iOS, you must upload the `.ipa` file to App Store using the **Transporter** application on a Mac. :::note Encryption algorithm When uploading an app to the Apple App Store, you are asked what encryption algorithm the app implements. The Encap SDK only uses standard encryption algorithms. It does not use any proprietary encryption algorithms that are not accepted by international standards. We use encryption provided both from within the Apple operating system, and from our third-party dependency OpenSSL. When presented with the **App Encryption Documentation** dialog box, select option **Standard encryption algorithms instead of, or in addition to, using or accessing the encryption within Apple's operating system**. ::: :::info Want to learn more? To learn more about our encryption and Apple requirements, see our [Apple export compliance requirements](/docs/mobile-identity/encap/sdk-ios/publish-your-app/apple-export-compliance-requirements/) page. ::: ### 7. Submit the app for review Finally, you need to send your build to review for Apple. Ensure that you fulfil the requirements below before you submit the app: 1. You must have a **Privacy Policy URL**. - Apple needs a privacy policy that is owned by your business. - You cannot use Signicat's privacy policy in this section. 2. If your app is not going to be available for distribution in France, then it is important to remove France from App Store Connect. To do this, go to **Monetization** > **Pricing and Availability**. :::tip Tip If you are not planning to distribute the app in France, then you can let us know about this beforehand. Apple allows this information to be specified in your app's `Info.plist`, which means that we can add that information to bypass these questions and streamline the submission process. To learn more about this, see [Complying with Encryption Export Regulations](https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations/) in the Apple developer documentation. ::: 3. You need to declare the collected data types. To do this: 1. Go to **Trust & Safety** > **App Privacy**. 2. Click **Edit** on **Data Types**, then select **Yes, we collect data from this app**. 3. On the next screen, pick the following from the list: - **Location** > **Precise Location** - **Diagnostics** > **Other Diagnostic Data** - **Other Data** 4. Select **App Functionality** and **No, data collected from this app is not linked to the user's identity**. --- ## Publish to Google Play Store :::note Do not enable automatic protection Our Authenticator App uses Promon SHIELD® for app security. It provides robust protection against unauthorised access and app tampering. As a result, you do not need to enable the **automatic protection** service in the Google Play Console when publishing the app. If **automatic protection** is enabled, it adds files to the app bundle that conflict with the Promon SHIELD® repackaging detection. This can cause app crashes and submission errors. ::: ## Overview In this guide, you can learn about how you can publish your app whilst meeting the necessary security requirements for platforms such as Google Play. To do this, you need to undertake the following: - Generate an upload key and app signing key for Android. This is required for secure distribution. - Securely share the certificates with Signicat. - Re-sign the shielded app for final distribution to app stores. ## How to publish your app ### 1. Create the signing key certificates 1. Generate the upload key certificate using Android studio or the command line. - This is used to sign the app when uploading it to the Google Play Store. - If you already have an existing upload key certificate, you can use this. :::info How do I do this? To learn how to do this, see the [Generate an upload key and keystore](https://developer.android.com/studio/publish/app-signing#generate-key) section in the Android developer documentation. ::: 2. Generate the App signing key certificate: - The **App signing key** is automatically generated the first time you create a release in the **Google Play Console**. - You can either use a Google generated key, or an existing one. 3. Download the certificates in the Google Play Console. :::info How do I do this? In the Google Play Console, navigate to **Setup**, then **App Integrity**. To learn how to do this, see the [Using Play App Signing](https://developer.android.com/studio/publish/app-signing#enroll) section in the Android developer documentation. ::: ### 2. Send the App signing certificate to Signicat Next, you need to securely share the app signing certificate with Signicat for further configuration. To do this: 1. In the Signicat Dashboard, navigate to the [Contact Us](https://dashboard.signicat.com/contact-us/tickets) service. 2. Create a new support ticket, where you share the following files from **Step 1**: - `deployment_cert.der` - `upload_cert.der` ### 3. Embed, build, sign and distribute :::note Note These steps are undertaken by Signicat. This means that they do not require any action from you. ::: 1. Once we have received your support ticket, we will embed the App Signing Certificate in the Shield configuration file. 2. We will build the shielded app and sign it with a Signicat key. 3. We will distribute the app to you by uploading it to our Nexus repository. ### 4. Re-sign the shielded app Once you receive the shielded app, you must re-sign it with your own credentials. To do this for Android App Bundle (AAB): 1. Remove the existing app signature by deleting the following files from the `.aab` Android App Bundle (AAB) archive: - `META-INF/CERT.SF` - `META-INF/CERT.RSA` - `META-INF/MANIFEST.MF` ```bash title="Example: Commands to remove the signatures" zip -d bundle.aab 'META-INF/CERT.SF' zip -d bundle.aab 'META-INF/CERT.RSA' zip -d bundle.aab 'META-INF/MANIFEST.MF' ``` 2. Re-sign the `.aab` file with your upload key: ```bash title="Example: How to re-sign with your upload key" apksigner sign --ks uploadkey-keystore.jks --ks-key-alias uploadkey-alias bundle.aab ``` ### 5. Upload and configure the shielded app Finally, you need to upload the shielded application (`.aab`) file to the Google Play Store using the Google Play Console. Before you can submit your app for review, you must complete the required declarations in the **App content** section of the Play Console as described in the sections below: ##### Privacy policy You must have a **Privacy Policy URL**. - Google Play Console requires a privacy policy that is owned by your business. - You cannot use Signicat's privacy policy in this section. ##### Data safety - You are required to fill out the **Data safety form**. To learn how to do this, see our [Data safety form](https://developer.signicat.com/docs/mobile-identity/encap/sdk-android/publish-your-app/data-safety-form/) guide. - To learn about what data is collected in the Authenticator App, see our [Collected data](https://developer.signicat.com/docs/mobile-identity/encap/sdk-android/publish-your-app/collected-data/) page. :::info Note Data collection may vary depending on your specific application configuration and enabled features. ::: ##### Financial features If your service provides financial features using the Authenticator App, then you may have to provide additional information. To learn about how to declare this, see the Google [Play Console Help](https://support.google.com/googleplay/android-developer/answer/13849271) documentation. --- ## Publish the app We deliver the Authenticator App app to you as an `AAB` or `IPA` file. As the customer, it is your responsibility to sign and publish the app on the Apple App Store and Google Play Store. ## How to publish the app The table below provides you with an overview of the process with requirements that you need to fulfil to publish your app: | **Step** | **Description** | **Customers responsibilities** | | :-- | :-- | :-- | | 1 | Create developer accounts | If you do not have developer accounts, then you need to register them before publishing. **Android**: Create a Google Play Developer Console account. **iOS**: Create an Apple Developer account with access to App Store Connect. | | 2 | Provide signing credentials | Send your app signing certificates and provisioning profiles (iOS) to Signicat. **Note**: See the guides below to learn how to do this. | | 3 | Receive the build from Signicat | Signicat uploads the branded production version of the Authenticator App as an AAB file (Android) or IPA file (iOS) to your folder in our Nexus repository. You must download this app. | | 4 | Sign the app (Android) | **Android only**: This step is only for Android versions of the Authenticator App. For iOS versions, you can skip this step. Sign the app with your keys. **Note**: See the guides below to learn how to do this. | | 5 | Create an API client for app review | In order for Apple and Google to fully test your app during the review process, they require an activation code from you. You can generate this by creating an API client specifically for the app review in the [Signicat Dashboard](https://dashboard.signicat.com/api-clients/). To do this: Follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). Ensure that you set permission **ReuseID MobileID Device API**. In the provided `how-to-test-guide.txt`, update the `clientId` and `clientSecret` using the API client credentials that you created in the Signicat Dashboard. | | 6 | Submit the app for review | Upload and submit the app for review to Google Play Console and Apple App Store Connect. | | 7 | Manage review feedback | The stores (Apple and Google) often come back with comments, required changes, or clarifications that you need to respond to and action. **Note**: Signicat can support you with this. | | 8 | Launch the app | Once approved, you control when you want to push to production and go live with your app. | :::warning Important You must remember to delete the API client that you created for the app review once the review process is completed. ::: :::note App review Both the Apple App Store and the Google Play Store have review processes. Approval is **not instant**. The review process often takes longer when you upload the app for the first time. Make sure that you start the publishing process early and add a buffer to your go-live date. ::: ## Guides To learn how to do this, see our platform-specific guides for publishing the app: * [**Publish to Google Play Store**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/google-play-store): Learn how to publish your Authenticator App to the Google Play Store * [**Publish to Apple App Store**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/apple-app-store): Learn how to publish your Authenticator App to the Google Play Store * [**Troubleshooting**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/troubleshooting): Find solutions to common issues and errors encountered when publishing your app to the stores --- ## Google Play Store :::tip Before you start Before you proceed with technical troubleshooting, ensure that you have completed all steps outlined in our [Publish to Google Play Store guide](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/google-play-store/). ::: ## App crashes after installing uploaded bundle from Play Console If the app crashes immediately after installing a bundle uploaded from the Play Console, then the cause is often a security violation triggered by the app's security solution, Promon SHIELD®. ### 1. Retrieve the logs Depending on your environment and access level, you can use one of the following methods to retrieve the crash logs: #### Method 1: Google Play Console (after upload) If the app is already distributed via any Google Play track (Internal, Closed, Open, or Production), Google automatically aggregates crash data. 1. Log in to the Google Play Console. 2. Select your application, then navigate to **Monitor and improve** > **Android vitals** > **Crashes and ANRs**. 3. Select the most recent crash event, then locate the **Stack trace** section. 4. Scan the log for the two-digit exception code. ```cmd title="Example: Exception code" qmfk.l: 01 ``` #### Method 2: Android Debug Bridge (local testing) If you have physical access to the device, you can stream logs directly to your terminal using the ADB tool. :::note Note If you have Android Studio installed, then ADB is already included. This means that you can use the integrated terminal. ::: 1. If you do not have Android Studio, then toy need to download the stand-alone **SDK Platform Tools** for your computer's operating system (Windows, macOS, or Linux). 2. Unzip the downloaded file, then either open your terminal (macOS/Linux) or Command Prompt (Windows) to navigate to it. ```cmd title="Example: Navigate to file" cd Desktop/platform-tools ``` 3. On the Android device, enable USB Debugging within the **Developer Options** menu, then connect the device to your computer with USB. 4. Run the command below to filter for high-priority errors: ```kotlin title="Example: Filter for high-priority errors on macOs/Linux" ./adb logcat *:E ``` ```java title="Example: Filter for high-priority errors on Windows" adb logcat *:E ``` 5. Launch the app to reproduce the crash. The terminal then outputs a `FATAL EXCEPTION` containing the required error code. :::note How to enable developer options To enable **Developer Options** on the mobile device: 1. Go to **Settings** > **About Phone** 2. Tap the **Build Number** seven times. **USB Debugging** is now available inside the newly-visible **Developer Options** menu. ::: ### 2. Identify the error code Once you have retrieved the logs: 1. Locate the two-digit code in the exception stack trace as shown in the following example: ```text title="Example: Exception stack trace" FATAL EXCEPTION: qmfk.l: 01 at qmfk.L.a(Unknown Source:112) at qmfk.L.b(Unknown Source:12) ``` 2. Use the exception code reference to determine which security check caused the app to terminate: :::CustomTable | **Code** | **Exception class** | **Description** | | :-- | :-- | :-- | | `00` | `RootException` | The device is rooted (has modified system access), which is blocked by the app's security policy. | | `01` | `RepackagingException` | The app's digital signature does not match the expected key. This usually happens if the wrong certificates were provided or if the resigning process failed. | | `02` | `EmulatorException` | The app is running on a virtual device (emulator) instead of a physical mobile device. | | `03` | `DebuggerException` | An active debugging tool is attached to the app, which is prohibited in production builds. | | `04` | `KeyboardException` | An untrusted keyboard was found. | | `05` | `ScreenReaderException` | An untrusted screen reader was found. | | `1a` | `DeveloperOptionsException` | **Developer Options** are enabled on the device. | | `1c` | `AdbStatusException` | **Android Developer Bridge** is active on the device. | | `21` | `BootloaderUnlockedException` | The mobile device's bootloader is unlocked. | ::: :::note Exception code reference This table does not contain an exhaustive list of all possible exception codes. If you detect an error code that is not listed above, then you can: - Refer to the official Promon SHIELD® documentation. - Contact us by creating a support ticket in the [Signicat Dashboard](https://dashboard.signicat.com/contact-us/tickets/new). ::: ### How to resolve The most common issue when deploying to the Play Store is **01: RepackagingException**. It occurs when the app's internal shielding detects that the certificate used to sign the app is different from the ones embedded in the shield configuration. To resolve this, you can verify the following points: #### 1. Mismatched certificates When preparing the app, you provided Signicat with your `deployment_cert.der` and `upload_cert.der` files using a support ticket in the Signicat Dashboard. If the keys used in your Google Play Console have changed, or if incorrect certificates were originally provided, then the app will crash. You must ensure you are signing the `.aab` file with the exact upload key that corresponds to the `upload_cert.der` that you sent us. #### 2. Incomplete resigning process Before signing the bundle with your upload key, you must remove the following default Signicat signatures from the `.aab` archive: - `META-INF/CERT.SF` - `META-INF/CERT.RSA` - `META-INF/MANIFEST.MF` :::tip Tip To confirm this process was followed exactly, review **Step 4** of the [Google Play Publishing Guide](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/google-play-store/#4-re-sign-the-shielded-app). ::: #### 3. Signature verification You can manually verify which certificate is currently attached to your app bundle. To do this, open your terminal and run: ```bash title="Example: Verify which certificate is currently attached" keytool -printcert -jarfile ``` #### 4. Disable Play Console automatic protection As noted in our [Google Play Publishing Guide](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/google-play-store), Google Play's automatic protection service adds files to the app bundle that conflict with Promon SHIELD® repackaging detection. You must ensure that this is disabled in the Play Console to prevent app crashes and submission errors. #### 5. Disable Play Integrity API Similarly to automatic protection in the Play Console, the Play Integrity API is not supported by the app's security solution. You must ensure that this is disabled to prevent conflicts. --- ## Troubleshooting(Troubleshooting) To learn about solutions to common issues and errors that you may encounter when publishing your app, make a selection using the buttons below: * [**Google Play Store**](/docs/mobile-identity/mobileid/authenticator-app/publish-the-app/troubleshooting/google-play-store): Troubleshoot common issues and errors when publishing to the Google Play Store --- ## Best practices This page contains useful information about best practices and considerations for anyone involved in implementing MobileID, for example developers, project managers and technical architects. The scope is for select topics that can assist you during your integration, such as key decisions, tips and ways to avoid common issues. ## Choose an authentication protocol An early decision that you need to make is which authentication protocol to use for MobileID authentication: | **Authentication protocol** | **Description** | | :-- | :-- | | ReuseID REST API | The ReuseID REST API is Signicat's native, proprietary solution. You need to use this API to conduct most supported operations, regardless of which authentication protocol you choose. This includes operations such as:
  • Creating ReuseID users
  • Registering MobileID devices
  • Conducting management operations
This means that if you use this API for authentication, then it is the only API you need to support.

**Note**: To learn more, see the [ReuseID API reference](/apis/reuseid/) documentation. | | OIDC Authorization Code Flow | The OpenID Connect (OIDC) authentication protocol with Authorization Code Flow allows you to integrate with MobileID as an eID method in the Signicat eID and Wallet Hub. This is an alternative to integrating with Signicat's ReuseID REST API.

The OIDC Authorization Code Flow is primarily designed for web applications and is not well suited for native mobile apps. In this flow, the client redirects the end-user to the authorisation server for authentication.

**Note**: To learn more, see the MobileID [Authorization Code](/identity-methods/mobileid/integration-guides/oidc/authorization-code-flow/) Flow integration documentation. | | OIDC CIBA Flow | The OpenID Connect (OIDC) authentication protocol with CIBA flow allows you to integrate with MobileID as an eID method in the Signicat eID and Wallet Hub. This is an alternative to integrating with Signicat's ReuseID REST API.

The OIDC CIBA flow (Client-Initiated Backchannel Authentication) is an extension to the OIDC protocol and is well-suited for headless applications that need to make backchannel authentication requests, such as with a mobile app.

This flow may be useful if for example you use a third-party access management software that integrates with and uses OIDC standards.

**Note**: To learn more, see the MobileID [CIBA Flow](/identity-methods/mobileid/integration-guides/oidc/ciba-flow/) integration documentation. | ## Check for outstanding transactions In an omnichannel environment, transactions can be initiated from several different channels and not only from the native mobile app. When your app initiates an authentication, it cancels any ongoing transactions that were started from other channels. To avoid this, you must implement a check for outstanding transactions by using a `startAuth` SDK call before your app starts an authentication itself. ## Avoid excess devices for a user In certain situations, the amount of devices registered to an end-user may be unnecessarily large. For example, this can happen if an end-user deletes and registers your app repeatedly. In these cases, you may reach the user device limit of 30 devices per end-user. If an end-user has more than 30 devices registered to them, then it could indicate suspicious behaviour such as malicious usage of your services. As a security measure: 1. When an end-user attempts to register a device that exceeds the user device limit, we notify you by returning the error message `exceeding_user_device_limit`. 2. Next, you can then investigate the situation further and if required, delete the previously registered devices using the [**Delete device**](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/getDevice) operation. Signicat automatically deletes devices that have not been used in the last 365 days, whereas you must manually delete other devices. :::tip Our recommendation You may find it useful to implement functionality where your end-users can manage their own devices logged into your website and delete their unused devices. ::: ## Activation code length The default activation code length is `10`. To ensure that you maintain good security, we do not recommend that you reduce this length for production accounts. If the end-user registers within your app and does not need to enter the activation code manually, then we recommend that you use a long activation code. ## Choose events (callback) or polling Events are our way of letting you know when something happens in one of our services. When an asynchronous operation completes, or when MobileID gets a notification that a device has changed state, MobileID publishes an event with the operation result. You can use the Signicat events service to subscribe to events, so that you automatically receive the result at your specified notification URI. This is often referred to as callback. You can also get the operation result back through polling. The result that you receive through the Signicat events service is the same as the result obtained by polling, but wrapped in a Signicat event object. For production, we always recommend that you use the Signicat events service instead of polling. This offers the best usability and responsiveness, as it has the least amount of latency. It also means that you do not need to conduct additional polling calls. :::info Want to learn more? - For information generic to all Signicat events, see the general [Events](/docs/dashboard/settings/events.mdx) documentation. - For information specific to MobileID, see the [MobileID](/docs/reuseid/events/#mobileid) section on the ReuseID **Events (callback)** page. ::: :::note Using our older REST API? If you are using the older MobileID REST API as opposed to the newer ReuseID REST API, then you can refer to the MobileID [Events (callback)](/docs/mobile-identity/mobileid/features/events/) page instead. ::: ## Segments When conducting certain operations on the **User** resource, it is possible to pass an optional parameter called `segment` in the request. The following operations support this parameter: - [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) - [**Update user**](pathname:///apis/reuseid/#tag/User/operation/updateUser) As the `segment` is then returned in the response of a respective transaction, it allows you to group the end-users and corresponding transactions based on a segmentation of your choice. For example, if your app is used by end-users across multiple countries, you could use segments to get statistics for app usage per country, In this example, you could segment your end-users using country codes such as `NO`, `SE`, `DK`. ## Resolve an external reference When a user is created with the [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) operation, we generate a valid UUID to identify it called a `userId`. This is required for carrying out most operations such as registration and authentication. You may already have your own internal customer references that you store and use for your customers. In the context of this product, we refer to it as an external reference. If you do not want to store the Signicat-generated `userId`, then you can use the [**Resolve external reference**](pathname:///apis/reuseid/#tag/User/operation/resolveUserIDByExtref) operation to supply the associated `externalRef` and fetch the `userId`. Once fetched, the `userId` can then be can then be used to start the subsequent operation as normal. --- ## Error codes(Mobileid) When you make a request to Signicat's ReuseID API and there is an error, a response with an error object is returned. If you have encountered an error, check the information on this page to investigate what might have caused the error and how to resolve it. If you require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::note Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: ## MobileID error object For MobileID, the error object can be made up from the following 7 fields: | **Field name** | **Description** | **Type/format requirement** | | :-- | :-- | :-- | | `type` | URI to the documentation that describes the error. | String | | `title` | A summary of the error type (this does not change between occurrences of the error). | String | | `code` | A machine-readable string, indicating the error code. This is a constant. | String | | `status` | The HTTP status code generated by the origin server (specific to this occurrence of the error). | HTTP status code | | `traceId` | The unique identifier of the request in the tracing system. This makes it possible for us to trace the history of the request in detail. | String | | `detail` | An explanation of the error (specific to this occurrence of the error). | String | | `invalidParams` | List of request parameters that have failed the validation. Contains the parameter name and the reason for validation failure. | String | ### Example responses ```json title="Example 1: MobileID response with error object" { "type": "https://api.signicat.com/mobileid/core/openapi.json", "title": "User entity does not exist", "code": "user_entity_does_not_exist", "status": 404, "traceId": "4bf239c088089f2bca77d3a413909f1d", "detail": "Failed fetching user with user ID : 90e1b3e5-93a7-458e-b42b-d1b57e65e26a and account ID : a-sdge-Abcdefghijk123456789." } ``` :::details What does this example mean? In this example, we can determine that the user entity (referred to by the `userId` in the request) does not exist. The `detail` describes which user ID and account ID this refers to, so that you can take action accordingly. ::: ```json title="Example 2: MobileID response with failed validation of request parameters" { "type": "https://api.signicat.com/mobileid/core/openapi.json", "title": "Invalid request parameter", "code": "invalid_request_parameter", "status": 400, "traceId": "4bf239c088089f2bca77d3a413909f1d", "detail": "Your request body parameters have failed validation." "invalidParams": [ { "name": "userId" "reason": "userId cannot be null or empty" }, { "name": "deviceId" "reason": "deviceId cannot be null or empty" } ] } ``` :::details What does this example mean? In this example, we can determine that multiple request parameters have failed the validation. The `invalidParams` describes which request parameters have failed the validation, so that you can modify them to pass the validation. ::: ## MobileID error codes :::note Generic errors Some of the MobileID-specific errors listed on this page are generic and can describe a number of possible issues. ::: | **Error code** | **HTTP Status** | **Description** | | :-- | :-- | :-- | | `access_token_missing` | 401 | The access token is missing from the request. | | `internal_error` | 500 | An internal error that requires no action from you. **Note**: In the rare case that this error persists, contact us by creating a support ticket in the [Signicat Dashboard](https://dashboard.signicat.com/contact-us/tickets/new). | | `internal_subsystem_error` | 4xx50x | An internal error that requires no action from you. **Note**: In the rare case that this error persists, contact us by creating a support ticket in the [Signicat Dashboard](https://dashboard.signicat.com/contact-us/tickets/new). | | `invalid_request` | 400404405406415 | A generic error that indicates the request is invalid. There are a number of possible causes for this error, such as: If a required query parameter is missing. If the wrong HTTP operation type is sent. | | `request_parsing_error` | 400 | There was an error when parsing the request, due to invalid JSON formatting. | | `unknown_property` | 400 | The property being passed in the request is either incorrect or misspelled. **Note**: You This error is also returned if the property being passed is correct, but its placement in the request is incorrect. | | `missing_identifier` | 400 | The device ID (`deviceId`) or user ID (`userId`) are missing in the resource path. | | `missing_request_parameter` | 400 | The device object, device ID (`deviceId`), or user ID (`userId`) are missing in the request payload. | | `invalid_request_parameter` | 400404 | A generic error that indicates the request contains an invalid parameter, or that no parameter has been supplied. There are a number of possible causes for this error, such as: If no parameter is supplied when you are resolving the external reference with an API call (`externalRef = null`). If the enumerated values being passed are not valid (if they are incorrect, or do not belong to the allowed set of values). | | `invalid_identifier` | 400404 | The supplied identifier uses an invalid character. For universally unique identifiers (UUIDs): User ID (`userId`) Device ID (`deviceId`) The allowed character set is: `REGEX = \"^[a-z0-9][a-z0-9\\-]*$\";` For other identifiers: External reference (`externalRef`) Attribute name (`attrName`) The allowed character set is: `REGEX = \"^[a-z_0-9][a-z_0-9~\\.\\-:@]*$\";` | | `identifier_too_long` | 400 | The supplied identifier exceeds the maximum character length. Maximum character lengths: External reference (`externalRef`): 128 characters Attribute name (`attrName`): 128 characters Attribute value (`attrValue`): 256 characters Any universally unique identifier (UUID): 36 characters | | `user_entity_does_not_exist` | 404 | The user entity referred to by the user ID (`userId`) does not exist. | | `user_entity_is_locked` | 409 | The user entity referred to by the user ID (`userId`) does exist, but is in a `LOCKED` state, and is therefore invalid for the requested operation. | | `user_entity_already_exists` | 409 | A new user entity cannot be added, as the user entity with that external reference (`externalRef`) already exists for this account. | | `device_does_not_exist` | 404 | The device referred to by the device ID (`deviceID`) does not exist. | | `device_is_locked` | 400 | The device referred to by the device ID (`deviceID`) does exist, but is in a `LOCKED` state. This means that it is invalid for the requested operation. | | `transaction_id_does_not_exist` | 404 | The transaction (with the transaction ID specified for this `GET` API call) cannot be found. | | `invalid_operation` | 400403404 | The operation cannot be cancelled, as the session for this operation does not exist. | | `exceeding_user_attribute_limit` | 400 | The maximum limit for the number of user attributes (100) has been exceeded. | | `exceeding_user_device_limit` | 400 | The maximum limit for the number of user devices (30) has been exceeded. | | `exceeding_sandbox_device_limit` | 405 | The maximum limit for the number of sandbox devices (100) has been exceeded. | | `multiple_pending_proofings` | 500 | There are multiple pending proofings. | | `user_proofing_does_not_exist` | 404 | The user proofing does not exist. | --- ## Account recovery(Features) ## About account recovery Our account recovery feature enables your end-users to recover their account when they have lost access to it, using your app. This means that your end-users can quickly return to your services, without the need to perform a costly and time-consuming re-onboarding. :::important PSD2 compliant This feature has been reviewed by a third party and is approved as a PSD2-compliant recovery method. ::: ### When to use account recovery Our account recovery feature is best fit for use cases when your end-user no longer has access to an active device. There are multiple reasons why an end-user may need to recover their account, such as: - If their device has been lost, broken or stolen. - If they have deleted your application (Android only). If your end-user still has access to their old device, then we recommend that you perform a recovery/activation of the new device by approving the operation on the old device instead. ## How does account recovery work? ### Prerequisites To be able to use our account recovery feature: - You need to configure account recovery in the application configuration. - Your end-user's device needs to have backup functionality enabled. This is enabled by default. :::note Supported backup providers The supported backup providers are Google Cloud and Apple iCloud. ::: - **Optional**: If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure this feature in the application configuration. ### Basic flow for an account recovery 1. Your end-user adds account recovery in your app. 2. As a result, the recovery credentials are stored in the cloud backup. 3. At a later point in time, your end-user performs an account recovery using your app that has implemented our account recovery feature. :::note Note All account recovery-related SDK operations require a valid authorisation token. To find out how to obtain this, see the [Token authorisation](#token-authorisation) section. ::: ### Token authorisation When you are using our SDKs for account recovery, you need to provide a token to authorise the operation. - Authorisation tokens are issued by our server when performing certain SDK operations. - In these operations, you need to set what purpose you will use the token for. - The token is returned back to your app as a response. - This token is used to authorise the next account recovery operation after a successful registration or authentication. :::info What does this mean? For example, this makes it possible to implement a flow that both registers the end-user and adds account recovery for the registration, without an additional authentication. ::: #### Operations that require a token An authorisation token is required for the following recovery-related operations: - `addOrUpdateRecovery` - `deleteRecovery` #### Operations that can yield a token The server will issue an authorisation token for the following operations: - `finishActivation` - `finishAuthentication` - `finishAddOrUpdateRecovery` - `finishRecovery` - `finishDeleteRecovery` :::note Note You will obtain an authorisation token for `addOrUpdateRecovery` by setting the `TokenPurpose` to `addOrUpdateRecovery` in one of the operations specified above. ::: ### What does an account recovery look like? The account recovery can be secured using server-side face authentication or a recovery code. We recommend server-side face authentication as: - It is more user-friendly, with no recovery code to remember. - It enhances security by not having a recovery code which could be shared. :::info What could it look like for your end-users? To see what account recovery with face authentication could look like for your end-users, see our [Figma prototype](https://www.figma.com/proto/weohzGQQacg4K8ZOZ5p4Zt/MobileID?page-id=5616%3A10660&node-id=5616-16688&viewport=608%2C373%2C0.68&t=FRNEYvAlTbJvdzc4-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=5616%3A16688). You can either click the app's interface, or use the arrows below the phone. ::: #### Add account recovery using face authentication Account recovery using face authentication can be added to a registration that has activated face authentication as an authentication method. The most common approach is to add account recovery in the same flow as when the end-user activates face authentication, however, it is possible to add account recovery at a later stage as well. :::warning Important If the device deletes server-side face authentication as an authentication method, then the device will no longer be able to recover using face authentication. ::: ##### Flow 1: Add recovery during activation of face authentication To add account recovery in the same flow as activating face authentication: 1. Your app performs `startAddOrUpdate` and `finishAddOrUpdate` SDK operations to add server-side face authentication as a new authentication method. Simultaneously, your app obtains a valid authorisation token. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery during activation of face authentication actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user starts process to add face authentication app->>mobileid: (SDK call) startAddOrUpdate mobileid-->>app: startAddOrUpdate response note over user, app: 1. End-user authenticates with biometrics or PIN2. End-user performs a facial scan to add face authentication app->>mobileid: (SDK call) finishAddOrUpdate with TokenPurpose addOrUpdateRecovery mobileid-->>app: finishAddOrUpdate response with an authorisation token app->>mobileid: (SDK call) startAddOrUpdateRecovery with an authorisation token mobileid-->>app: startAddOrUpdateRecovery response app->>mobileid: (SDK call) finishAddOrUpdateRecovery mobileid-->>app: finishAddOrUpdateRecovery response mobileid->>sp: (Callback) new recovery added sp-->>mobileid: OK ``` ::: ##### Flow 2: Add recovery at a later stage To add account recovery at a later stage, when server-side face authentication has already been added as an authentication method for the device: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery. :::details Sequence diagram ```mermaid sequenceDiagram title Add recovery at a later stage actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user starts process to add account recovery app->>sp: Start authentication sp->>mobileid: POST /authentication with userId and deviceId mobileid-->>sp: authentication response sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication with TokenPurpose addOrUpdateRecovery mobileid-->>app: finishAuthentication response with an authorisation token app->>mobileid: (SDK call) startAddOrUpdateRecovery with an authorisation token mobileid-->>app: startAddOrUpdateRecovery response app->>mobileid: (SDK call) finishAddOrUpdateRecovery mobileid-->>app: finishAddOrUpdateRecovery response mobileid->>sp: (Callback) new recovery added sp-->>mobileid: OK ``` ::: #### Add account recovery using recovery code Account recovery using a recovery code can be added either during device registration, or at a later stage to an existing registration. ##### Flow 1: Add recovery during a new registration To add account recovery during a new registration: 1. Your app obtains a valid authorisation token by performing a standard registration, using `startActivation` and `finishActivation` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery during a new registration actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user opens app app->>sp: Start registration sp->>mobileid: POST /registrations with userId mobileid-->>sp: activationCode sp-->>app: activationCode app->>mobileid: (SDK call) startActivation with activationCode mobileid-->>app: startActivation response note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishActivation with TokenPurpose addOrUpdateRecovery mobileid-->>app: finishActivation response with an authorisation token app->>mobileid: (SDK call) startAddOrUpdateRecovery with an authorisation token mobileid-->>app: startAddOrUpdateRecovery response note over user, app: End-user selects a recovery code app->>mobileid: (SDK call) finishAddOrUpdateRecovery mobileid-->>app: finishAddOrUpdateRecovery response mobileid->>sp: (Callback) new recovery added sp-->>mobileid: OK ``` ::: ##### Flow 2: Add recovery at a later stage To add account recovery at a later stage to an existing registration: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an add recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. 3. As a result, the recovery credentials are stored in the cloud backup. :::details Sequence diagram ```mermaid sequenceDiagram title Add account recovery to an existing registration actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user starts process to add account recovery app->>sp: Start authentication sp->>mobileid: POST /authentication with userId and deviceId mobileid-->>sp: authentication response sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication with TokenPurpose addOrUpdateRecovery mobileid-->>app: finishAuthentication response with an authorisation token app->>mobileid: (SDK call) startAddOrUpdateRecovery with an authorisation token mobileid-->>app: startAddOrUpdateRecovery response note over user, app: End-user selects a recovery code app->>mobileid: (SDK call) finishAddOrUpdateRecovery mobileid-->>app: finishAddOrUpdateRecovery response mobileid->>sp: (Callback) new recovery added sp-->>mobileid: OK ``` ::: #### Perform an account recovery To perform an account recovery, your app is restored with `startRecovery` and `finishRecovery` SDK operations, using data from the could backup. - The device ID (`deviceId`) that you use as a reference remains unchanged when your app is recovered. - Once a recovery has been performed, it cannot be used again. - To be able to recover again, your end-users need to add a new recovery on the device. - For recovery using face authentication, the face authentication method is automatically activated for the recovered device. :::details Sequence diagram ```mermaid sequenceDiagram title Perform account recovery actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user starts recovery app->>mobileid: (SDK call) startRecovery mobileid-->>app: startRecovery response note over user, app: End-user either performs a face authentication or enters their recovery code app->>mobileid: (SDK call) finishRecovery mobileid-->>app: finishRecovery response mobileid->>sp: (Callback) account recovery performed sp-->>mobileid: OK ``` ::: #### Manage account recovery Account recovery can be managed with operations to update or delete a recovery. ##### Update a recovery To update a recovery: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs an update recovery flow using `startAddOrUpdateRecovery` and `finishAddOrUpdateRecovery` SDK operations. ##### Delete a recovery To delete a recovery: 1. Your app obtains a valid authorisation token using `startAuthentication` and `finishAuthentication` SDK operations. This is used for the following account recovery operation. 2. Your app performs a delete recovery flow using `startDeleteRecovery` and `finishDeleteRecovery` SDK operations. :::note Note Deleting a recover with face authentication does not delete the face authentication method. ::: ## How to implement account recovery To implement our account recovery feature, you need to: - [Configure the application configuration](#configure-the-application-configuration). - [Configure the mobile SDK](#configure-the-mobile-sdk). ### Configure the application configuration To use account recovery, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to perform recoveries. To do this: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > **Features** > [Account recovery](https://dashboard.signicat.com/mobileid/features/account-recovery). 2. Use the toggle button to enable account recovery, then click **Save**. :::info Want to learn more? To learn more about the configurable properties, see the [Account recovery](/docs/mobile-identity/mobileid/features/application-configuration.mdx#account-recovery) section in our **Application configuration** feature documentation. ::: :::warning Recovery using face authentication If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure server-side face authentication in the application configuration. To learn how to do this, see the configuration section in our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/#configure-the-application-configuration) feature documentation. If you want to use a recovery code to protect the recovery backups, you can skip this step. ::: ### Configure the mobile SDK You must also configure the SDK for account recovery. To learn how to do this, read the platform-specific documentation using the buttons below: * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/account-recovery): Learn how to configure the Android SDK for account recovery * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/account-recovery): Learn how to configure the iOS SDK for account recovery ## Events (callback) Most account recovery operations, including adding and performing an account recovery, are client-initiated operations. We can send events to your server to let it know when these operations occur. To get events, you need to set up subscriptions in the Signicat Dashboard. To learn how to do this, see our [Events](/docs/mobile-identity/mobileid/features/events.mdx) documentation. ## API integration We provide endpoints for account recovery that allow you to optionally integrate with the ReuseID REST API. With these endpoints, you can carry out operations such as: - Determine if a device has set recovery credentials. - Retrieve information about recovery data and the recoveries performed from devices. - Disable recovery for a device ### Get general recovery information To get general information about all recoveries performed for an end-user's device, you can use the [Get device](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/getDevice) endpoint in the ReuseID **MobileID device management** API. The response returns information about an end-user's device, and allows you to verify whether account recovery has been enabled for that specific device. :::note Note The recovery information is contained within the device details object. To return this object in the response, you must use query parameter: ``` detailed=true ``` ::: ### Get detailed information about a recovery To get detailed information about a specific recovery performed for an end-user's device, you can use the [Get details of account recovery](pathname:///apis/reuseid/#tag/MobileID-account-recovery/operation/getAccountRecovery) endpoint in the ReuseID **MobileID account recovery** API. The response lists risk data and all other attributes created as part of the recovery process, if the operation is finished. :::note Note You need the transaction ID (`transactionId`) of the recovery to use this endpoint. To learn how to obtain this, see the [Useful information](pathname:///apis/reuseid/#tag/MobileID-account-recovery/Useful-information) section for this API. ::: ### Disable recovery for a device To disable recovery for a specific device, you can use the [Update recovery lock](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/putRecoveryLockStatus) endpoint. If recovery lock is enabled, then the device will be unable to perform any operations related to account recovery. :::note Note Locking recovery prevents the device from adding and performing recoveries, even when recovery is enabled in the application configuration. ::: --- ## App attestation(Features) ## About app attestation Our app attestation feature gives applications additional security, as it prevents third-party use of our APIs. Using this feature guarantees that our Encap server communicates with the correct app. Without app attestation, any mobile client with a valid AppID and end-to-end (E2E) public key can call and use our Encap mobile client APIs. This could allow a third party to create a malicious app, which can pose security and privacy risks. ## How does app attestation work? ### Play Integrity for Android On Android devices, we offer **Play Integrity**, which is provided by Google as part of the Android platform. Play Integrity lets you enforce the use of trusted Android devices and genuine apps that have been installed from the Google Play Store. We use the [Play Integrity Attestation API](https://developer.android.com/google/play/integrity), which assesses the integrity of the device that an app is running on. :::tip Note If your app generates more traffic than the default Play Integrity API quota, your API requests may return errors. You can find more details about [Play Integrity API quota and monitoring](https://developer.android.com/google/play/integrity/overview) in the Android developer documentation. ::: ### App Attest for iOS On iOS devices, we offer **App Attest**, which is provided by Apple as part of the iOS platform. App Attest gives your app a way to assert its validity, by enforcing the use of trusted apps with genuine SDKs. This feature is available on Apple devices running iOS version 14 and later. You can find an overview of the service backing this feature in the [Apple developer documentation](https://developer.apple.com/documentation/devicecheck/validating-apps-that-connect-to-your-server). ## App attestation response object The attestation result is provided in the response as the `attestation` object. :::CustomTable{columnWidths="25% 75%"} | **Field name** | **Description** | | :-- | :-- | | `play_integrity_status` | Play Integrity attestation status for the device. See [Play Integrity statuses](pathname:///apis/reuseid/#section/Common-concepts/Play-Integrity-statuses) in our ReuseID API reference documentation for a list of possible values. | | `play_integrity_date` | Date of when the Play Integrity attestation was performed. | | `app_attest_status` | AppAttest attestation status for the device. See [App Attest statuses](pathname:///apis/reuseid/#section/Common-concepts/App-Attest-statuses) in our ReuseID API reference documentation for a list of possible values. | | `app_attest_date` | Date of when the App Attest attestation was performed. | ::: **Example: Attestation result for Android** ``` "attestation" : { "play_integrity_status" : "VERIFIED", "play_integrity_date" : "2019-09-20T13:14:01.984UTC" } ``` **Example: Attestation result for iOS** ``` "attestation" : { "app_attest_status" : "VERIFIED", "app_attest_date" : "2019-09-20T13:14:01.984UTC" } ``` ## How to configure app attestation To use our app attestation feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK You can use the buttons below to learn how to configure the mobile SDK for app attestation. * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/app-attestation): Learn how to configure the Android SDK for app attestation. * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/app-attestation): Learn how to configure the iOS SDK for app attestation. ### Configure the application configuration To enable and configure app attestation, you need to update your application configuration. You can see what values need to be set in the [App attestation](/docs/mobile-identity/mobileid/features/application-configuration/#app-attestation) section in the **Application configuration** feature documentation. To find out how to set these properties, see the [Make changes to your configuration](#make-changes-to-your-configuration) section on this page. #### Attestation modes The app attestation feature can be used in multiple modes: :::note OFF The `OFF` mode means that attestation is not performed. By default, attestation is turned `OFF`. ::: :::note OPTIONAL The `OPTIONAL` mode means that attestation is performed. If attestation fails, then the transaction will not fail, and a new attestation is performed on the next transaction. ::: :::note REQUIRED The `REQUIRED` mode means that attestation is performed. If attestation fails, then the transaction will fail and the device is locked. The device must perform a successful attestation before it can be used for future transactions. Attestation is triggered on new registrations, or the first authentication if the registration already exists. **Note**: Devices running versions of iOS older than iOS 14 will always fail if the mode is `REQUIRED`, due to requirements by the Apple App Attest API. ::: #### Make changes to your configuration To update your application configuration with the necessary properties, you can either: - Use the [Signicat Dashboard](https://dashboard.signicat.com/mobileid/features/app-attestation). - Use our [MobileID Admin REST API](pathname:///apis/mobileid-admin/#tag/Application-configuration). --- ## App security(Features) ## About app security App security enables you to protect your app from various threats and attacks with mechanisms such as app hardening and runtime application self-protection (RASP). App security provides proactive security against a wide range of attacks, such as tampering, debugging, code injection, code modification and stealing of data from your app. ### Mobile app hardening Mobile app hardening describes the process of improving the security measures of an app, to protect it from fraud techniques. This makes it harder for potential hackers to reverse engineer and tamper with your app. ### Runtime application self-protection (RASP) RASP (runtime application self-protection) protects your apps from malicious behaviour. It uses runtime instrumentation to monitor behaviour and stop threats in real time. ## How does app security work? App security is delivered in packages for iOS and Android, and shields your app in an automated and seamless process. It contains both prevention and detection features to counter threats found. - It secures your app at both runtime and at rest, through various security features. - It can detect whether its surrounding environment can be trusted during runtime. ### Features Threats and attacks can originate from sources such as hackers, users and malware. App security protects your mobile app against: - Malware - Debugging, such as Java or native debuggers - Emulator/fake execution environment - Cloning of the device - Rooting and jailbreaking - Code injection (runtime library injection) - Hooking-frameworks - Repackaging, such as fake or manipulated apps - System and end-user screenshots - Keylogging from untrusted keyboards - Keylogging and screen-scraping from untrusted screen-readers - Native code-hooks - External screen sharing - Overlay attacks, by overlay detection mechanisms - Tampering, by performing in-depth integrity checks of files and assets #### Anti-tampering RASP is a crucial part of app security in mobile devices. It is achieved using the products capabilities to detect whether the app's surrounding environment can be trusted. RASP secures from inside the app and uses runtime information to detect, protect, report and block attacks. App security includes the following anti-tampering capabilities: - Debugger and emulation detection. - Privilege escalation detection; it detects if the device is jailbroken or rooted. - Integrity checks; it detects whether the app or device configuration has been altered. #### Repackaging protection Repackaging protection is obtained through application binding. This ensure that app security cannot be removed from a protected app and repackaged. Various forms of integrity checks are performed when a shielded app is launched, to verify that the app has not been repackaged. #### Code obfuscation Code obfuscation scrambles the source code to make it harder for an attacker to reverse engineer how an app works. An app which is harder to read is harder to attack, making it more difficult to steal its intellectual property or to repackage it. App security is fully obfuscated by default. ### Handling When app security performs security checks, it can be configured to either: - Exit directly when it detects a security problem. - Notify the app about the security event using a callback interface. By using the callback interface, you can notify about possible security problems before the app is terminated, or notify a backend system for usage analytics. For example, you can notify the backend about the number of rooted or jailbroken devices that are using your app. ## App security partnership We currently deliver app security through our partnership with Promon and their product [Promon SHIELD® for Mobile](https://promon.io/products/mobile). We strongly recommend that you implement tools for app security, regardless of whether it is using Promon SHIELD® through Signicat, or by sourcing one of your own providers. --- ## Application configuration(Features) An **application configuration** is a specific set of **application attributes** for a mobile application. These attributes determine how the application should work. ## How it works MobileID comes with a standard application configuration. It is possible to change the default values in this configuration to suit your needs. To do this, you can either: - Make changes to your application configuration using the [Update properties of application configuration](pathname:///apis/mobileid-admin/#tag/Application-configuration/operation/updateAppConfigurationProperties) endpoint in our MobileID Admin API. - Send your preferences to us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and we will update them for you. You can find an overview of all application configuration properties and their default values in the tables below. ## Configurations ### Account recovery You can use the properties below to configure the MobileID **Account recovery** feature for your application. :::info Want to learn more? To learn more about this feature and how to configure it, see our [Account recovery](/docs/mobile-identity/mobileid/features/account-recovery) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `recoveryEnabled` | Enable users to set up cloud-based recovery credentials. | `true`, `false` | `false` | | `recoveryCodeMinLength` | The minimum number of characters that the recovery code can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `0` to `MAXINT` | `6` | | `recoveryCodeMaxLength` | The maximum number of characters that the recovery code. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `0` to `MAXINT` | `50` | | `recoveryCodeFormat` | The types of characters that can be used for the recovery code can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | `ALPHA`, `ALPHANUMERIC`, `ANY`, `NUMERIC` | `NUMERIC` | | `recoveryCodeAmountFailuresAllowed` | The amount of failed recovery code attempts allowed for any client, before the recovery for the client is locked. | From `0` to `MAXINT` | `3` | ::: ### App attestation You can use the properties below to configure the MobileID **App attestation** feature for your application. :::note Properties for both platforms This table describes properties for both Android and iOS: - For iOS devices, we use **App Attest**. - For Android devices, we use **Play Integrity**. ::: :::info Want to learn more? To learn more about this feature and how to configure it, see our [App attestation](/docs/mobile-identity/mobileid/features/app-attestation) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `attestationAndroidPlayIntegrityMode` | Determines whether Play Integrity attestation is performed, and how the request is handled. This is reflected in three different modes: `REQUIRED` means that Play Integrity attestation is performed. If attestation fails, then the device operation will fail. `OPTIONAL` means that Play Integrity attestation is performed. If attestation fails, then the device operation will not fail, and a new attestation is performed on the next request. It is up to you what action is taken on the result. `OFF` means that Play Integrity attestation is not performed. | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `attestationAndroidPlayIntegrityTimeout` | The number of milliseconds before timeout for a request made to Play Integrity. | `1` to `MAXINT` | | | `attestationAndroidPlayIntegrityDecryptionKey` | Play Integrity attestation decryption key, used to decrypt the integrity token. | Base64 encoded value | | | `attestationAndroidPlayIntegrityVerificationKey` | Play Integrity attestation verification key, used to validate the integrity token. | Base64 encoded value | | | `attestationAndroidPackageName` | The APK package name. This is required if `attestationAndroidPlayIntegrityMode` is set to `REQUIRED` or `OPTIONAL`. | String | | | `attestationIosAppAttestMode` | Determines whether Apple App Attest Service (used to validate whether an application runs on a real iOS device) is performed, and how the request is handled. This is reflected in three different modes: `REQUIRED` means that App attestation is performed. If attestation fails, then the device operation will fail. **Note**: Devices running versions of iOS older than iOS 14 will always fail if the mode is `REQUIRED`, due to requirements by Apple. `OPTIONAL` means that App attestation is performed. If attestation fails, then the device operation will not fail, and a new attestation is performed on the next request. It is up to you what action is taken on the result. `OFF` means that App attestation is not performed. | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `attestationIosAppAttestEnvironment` | Determines the environment where an iOS app that uses App attestation validates itself. | `PRODUCTION`, `DEVELOPMENT` | `PRODUCTION` | | `attestationIosAppAttestTimeout` | The number of milliseconds before timeout for an iOS app attestation request. | From `1` to `MAXINT` | `20000` | | `attestationIosAppAttestAppId` | An iOS app ID, which is a concatenation of: A 10-digit team identifier A period The app's `CFBundleIdentifier` value | String | | ::: ### Application behaviour You can use the properties below to configure your application's behaviour. :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `activationCodeLength` | The number of characters that the generated activation code will be. | From `6` to `MAXINT` | `10` | | `activationCodeType` | The types of characters that can be used for the generated activation code. | `ANY`, `NUMERIC`, `ALPHA`, `ALPHANUMERIC` | `NUMERIC` | | `allowedAuthMethods` | The allowed authentication methods, given as a comma-separated list. It is mandatory to have `DEVICE` as an allowed authentication method. For single-factor authentication, you need to explicitly specify it in the start authentication request. | For allowed values, see [Authentication methods](pathname:///apis/reuseid/#section/Common-concepts/Authentication-methods) in the API reference documentation. | `DEVICE`, `DEVICE:PIN`, `DEVICE:STRONG_TOUCH_ID`, `DEVICE:IOS_FACE_ID`, `DEVICE:ANDROID_BIOMETRIC_PROMPT`, `DEVICE:SERVER_SIDE_FACE` | | `allowedAuthMethodsForAuthAndActivate` | The allowed authentication methods when adding a new authentication method through our `AddOrUpdate` operation. Authentication methods are given as a comma-separated list. All authentication methods specified here must be present in the `allowedAuthMethods` parameter. | For allowed values, see [Authentication methods](pathname:///apis/reuseid/#section/Common-concepts/Authentication-methods) in the API reference documentation. | `DEVICE:PIN`, `DEVICE:SERVER_SIDE_FACE` | | `amountFailuresAllowed` | The amount of failed PIN authentications allowed for any client, before the end-user is locked out. | From `0` to `MAXINT` | `3` | | `encapApiBlacklistAndroid` | Which Android client SDK versions to blocklist (sometimes referred to as blacklist). Devices running blocklisted versions will be rejected/denied. | Comma-separated semantic version. **Example**: `"3.5.3, 3.6.8"` | | | `encapApiBlacklistIos` | Which iOS client SDK versions to blocklist (sometimes referred to as blacklist). Devices running blocklisted versions will be rejected/denied. | Comma-separated semantic version. **Example**: `"3.5.3, 3.6.8"` | | | `maxPinCodeLength` | The maximum number of characters that the PIN can be. | From `1` to `MAXINT` | `6` | | `minimumRequiredEncapApiVersionAndroid` | The minimum Android client SDK version allowed. This can only be used to narrow down the allowed Android SDK versions (not extend). **Example**: If the minimum supported client version on the server is `"3.5.0"`, and someone wants to only allow `"3.6.0"`, this can be achieved. However, specifying `"3.3.0"` would have no effect, as it is below the minimum supported client version on the server. | Semantic version. **Example**: `"3.7.0"` | | | `minimumRequiredEncapApiVersionIos` | The minimum iOS client SDK version allowed. This can only be used to narrow down the allowed iOS SDK versions (not extend). **Example**: If the minimum supported client version on the server is `"3.5.0"`, and someone wants to only allow `"3.6.0"`, this can be achieved. However, specifying `"3.3.0"` would have no effect, as it is below the minimum supported client version on the server. | Semantic version. **Example**: `"3.7.0"` | | | `pinCodeLength` | The minimum number of characters that the PIN can be. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | From `1` to `MAXINT` | `6` | | `pinCodeType` | The types of characters that can be used for the PIN. **Note**: This parameter is a hint to the client, and is not enforced by the server. However, it is enforced in the client SDK. | `ANY`, `NUMERIC`, `ALPHA`, `ALPHANUMERIC` | `NUMERIC` | | `sessionExpiry` | The number of milliseconds that a new device operation session remains valid for. After this time has elapsed, the session can no longer be used for any operations. **Note**: This value cannot exceed the maximum configured value of `187200000`. | From `1` to `187200000` | `187200000` | | `maximumSessionExpiry` | The maximum number of milliseconds that the `sessionExpiry` can be set to. **Note**: Only Signicat can set this property. To update it, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. | From `1` to `MAXINT` | `187200000` | | `clientDebugDataEnabledOsTypes` | A comma-separated list of operating system types to enable client debug data for. It can be set for neither, one, or both platforms. **Note**: Only Signicat can set this property. To update it, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. | `IOS`, `ANDROID` | | `lockScope` | This setting determines the lock behavior following failed authentication attempts. `AUTH_METHOD`: Only the current authentication method is locked. The end-user can unlock it using another valid, unlocked method. `DEVICE`: The entire device is locked, making all authentication methods unusable. You must unlock the device using the [Update device](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/updateDevice) endpoint. | `DEVICE`, `AUTH_METHOD` | `DEVICE` | ::: ### Cleanup of inactive devices The property below is used to configure the cleanup of inactive devices. :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `inactiveDeviceDeleteRetentionTime` | The number of days that a device can be inactive before it is deleted. The inactive period starts from the time when the device was last used. **Note**: Only Signicat can set this property. To update it, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. | From `90` to `MAXINT` | `365` | ::: ### Face authentication You can use the property below to configure the MobileID **Face authentication** feature for your application. :::info Want to learn more? To learn more about this feature and how to configure it, see our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `serverSideFaceEnabled` | Determines whether the server can use the **Face authentication** feature. | `true`, `false` | `true` | ::: ### Geofencing You can use the properties below to configure the MobileID **Geofencing** feature for your application. :::info Want to learn more? To learn more about this feature and how to configure it, see our [Geofencing](/docs/mobile-identity/mobileid/features/geofencing) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `geofencingActivationMode` | Determines if or how geofencing is used for registration. This is reflected in three different modes: `REQUIRED` means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the registration request will fail. `OPTIONAL` means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the registration request will be performed. It is up to you what action is taken on the result. `OFF` means that a device location check is not performed. | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `geofencingActivationAllowedContinents` | Comma-separated list of continents where registration is allowed, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `geofencingActivationAllowedCountries` | Comma-separated list of countries where registration is allowed, in an ISO 3166-1 alpha-2 two-letter country code format. These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `geofencingActivationDeniedCountries` | Comma-separated list of countries where registration is not allowed, in an ISO 3166-1 alpha-2 two-letter country code format. These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `geofencingAuthenticationMode` | Determines if or how geofencing is used for authentication. This is reflected in three different modes: `REQUIRED` means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the authentication request will fail. `OPTIONAL` means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the authentication request will be performed. It is up to you what action is taken on the result. `OFF` means that a device location check is not performed. | `REQUIRED`, `OPTIONAL`, `OFF` | `OFF` | | `geofencingAuthenticationAllowedContinents` | Comma-separated list of continents where authentication is allowed, in a two-letter continent code format. | `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania), `SA` (South America) | | | `geofencingAuthenticationAllowedCountries` | Comma-separated list of countries where authentication is allowed, in an ISO 3166-1 alpha-2 two-letter country code format. These countries are in addition to those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `geofencingAuthenticationDeniedCountries` | Comma-separated list of countries where authentication is not allowed, in an ISO 3166-1 alpha-2 two-letter country code format. These countries will be excluded from those covered by the allowed continents parameter. | You can find a list of countries and corresponding codes at [GeoNames](https://www.geonames.org/countries/). | | | `geofencingTimeout` | The maximum number of milliseconds to wait for the location lookup and reverse geocoding to complete on the SDK. The timing starts when the SDK calls the finish operation. If the timeout is exceeded, then the SDK will continue without a country. | From `0` to `MAXINT` | `10000` | ::: ### Hardware-protected keys :::info See our feature documentation To learn about hardware-protected keys and how to configure them, see our MobileID [Hardware-protected keys](/docs/mobile-identity/mobileid/features/hardware-protected-keys/) feature documentation. ::: ### Push notifications You can use the properties below to configure push notifications for your application. :::note Properties for both platforms This table describes properties for both Android and iOS: - For iOS devices, we use **Apple Push Notification service (APNs)**. - For Android devices, we use **Firebase Cloud Messaging (FCM)**. ::: :::info Want to learn more? To learn more about this feature and how to configure it, see our [Push notifications](/docs/mobile-identity/mobileid/features/push-notifications/) feature documentation. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `apnConfig` | The APN server configuration that defines where to reach the APNs. | `PRODUCTION`, `SANDBOX` | `PRODUCTION` | | `apnExpiry` | The number of milliseconds that APNs will try to deliver the message for. If not delivered within this time, then the message is discarded. **Note**: APNS will attempt to deliver the message at least once, regardless of the set expiration time. | From `1` to `MAXINT` | `1` | | `apnsBundleId` | Apple's bundle ID for the application. This is used as a topic on the push message sent to APNs, and is required when using APNs tokens. | String | | | `apnsNotificationSoundEnabled` | Determines whether a notification sound is played on iOS devices when the device receives a push message. If the option is set to `true`, the 'default' sound on the device is played when a push is received. If the option is omitted or set to `false`, no sound is played. **Note**: This parameter only applies to iOS devices. On Android, the app itself determines whether a notification sound is played. | `true`, `false` | `true` | | `apnsTimeSensitiveInterruptionLevelEnabled` | Sets the interruption level for push messages to iOS devices to 'time-sensitive'. If set to `true`, push notifications are given a higher priority and can notify users even when the device is in 'Focus' mode. If set to `false`, the default interruption level 'Active' is assumed by the device. | `true`, `false` | `false` | | `nativePushEnabled` | Enables the server to send push messages with Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs). | `true`, `false` | `false` | | `firebaseServiceAccount` | The contents of the `serviceAccount.json` file (credentials file), for your Firebase Cloud Messaging (FCM) project. **Note**: This has to be supplied to us Base64-encoded. | String | | | `firebaseTimeToLive` | The maximum lifespan of the message in milliseconds, for Firebase Cloud Messaging (FCM). The default value is `0` , which means to deliver the message 'now or never'. FCM guarantees best effort for messages with this lifespan. | From `0` to `MAXINT` | `0` | ::: ### Risk data You can use the property below to configure risk data for your application. :::info What is risk data? Risk data is a set of risk attributes that can be collected for each operation. The `enabledRiskData` property determines which attributes are collected and returned in the operation response. ::: :::CustomTable | **Property name** | **Description** | **Allowed values** | **Default value** | | :-- | :-- | :-- | :-- | | `enabledRiskData` | Determines which risk data to collect. You can either: Collect only selected risk data (including always collected risk data). Collect only always collected risk data. | Select specific attributes, given as a JSON array. **Note**: In addition to `location`, see the [Risk attributes](pathname:///apis/reuseid/#section/Common-concepts/Risk-attributes) in the **Common concepts** section of the ReuseID API reference documentation for allowed values. **or** Leave this field empty (`null`). | | ::: #### Always collected risk data Some risk data is always collected, for debugging purposes. This means that for `enabledRiskData`: - If you leave this field empty (`null`), the *always collected* risk data will still be returned. - If you specify risk attributes, the *always collected* risk data will be returned in addition to those you have specified. You can find a list of what risk data is always enabled in the ReuseID API reference documentation. See [Risk attributes](pathname:///apis/reuseid/#section/Common-concepts/Risk-attributes) in the **Common concepts** section. #### Location risk data Location (`location`) is a risk data attribute that describes the location of the device used in the operation. It is returned as its own object in the operation response instead of in the risk attributes (`riskAttributes`) object. You can enable location risk data by adding value `location` to the enabled risk data (`enabledRiskData`) in the application configuration. --- ## Broadcast ## About broadcast Our broadcast feature allows you to broadcast authentication and signing operations to all of your end-user's active devices. This enables your end-users to finish the operation on whichever device is most convenient for them. Diagram showing how broadcast works ## How does broadcast work? When using broadcast, the authentication or signing operation will be broadcast to all of the end-user's active devices. The devices will receive a push notification if this has been configured in the application configuration. It is up to the end-user to select the device on which the operation will be finished. From the end-user's perspective, a broadcast operation looks the same as an operation that was not broadcast. The only exception is that they will receive the operation on all of their devices when broadcast is used, as opposed to just the one device that was specified if not. Once the operation is completed on one of these devices, then the operation cannot be completed on any other device that has also received the broadcast. :::tip Note A broadcast operation is billed the same way as **one** normal operation. ::: ## Configuration options You can enable broadcast for authentication and signing operations. Broadcast is disabled by default. To enable the feature, you have to set broadcast to true in the `operationProperties` object in the operation request. :::CustomTable{columnWidths="25% 75%"} | **Broadcast mode** | **Description** | | :-- | :-- | | `false` | Broadcast is disabled. This is the default value. When broadcast is set to `false`, the device object in the operation request is mandatory. You must explicitly specify the device (specified by the `deviceId`) on which the operation will be carried out. | | `true` | Broadcast is enabled. When broadcast is set to `true`, the device object in the operation request should either be empty, or not supplied entirely. | ::: **Example: Enabling broadcast in the operation request** ``` { "userId": "0e99b25c-abde-4553-973b-8d94d49cd87e", "operationProperties": { "broadcast": true } } ``` You can find more information about broadcast in the **Start authentication** operation, in our [ReuseID API reference documentation](pathname:///apis/reuseid/#tag/MobileID-Authentication/operation/addAuthentication). --- ## Certificate pinning(Features) Certificate pinning is commonly used in mobile applications to ensure that the app only communicates with a trusted backend, by validating the server's TLS certificate or public key. This mitigates risks such as: - Man-in-the-middle (MITM) attacks - Compromised or rogue certificate authorities (CA) - TLS interception through proxies or malware Traditionally, this is achieved by embedding (often referred to as _pinning_) a server certificate or public key in the application and validating it during the TLS handshake. ## How does it work for MobileID? MobileID does not rely on traditional TLS certificate pinning at the transport layer. Instead, it provides equivalent or stronger security guarantees through an end-to-end encrypted (E2EE) application layer. While certificate pinning secures the transport layer, E2EE secures both the transport and the application layer. To learn more about how these security mechanisms differ, see the table below: :::CustomTable{columnWidths="25% 75%"} | **Security mechanism** | **Description** | | :-- | :-- | | Certificate pinning | A security mechanism where a mobile app is coded to only trust a specific, pre-defined server certificate or public key. This is done to prevent MITM attacks, where an attacker might use a fraudulent certificate to intercept the communication between the app and the server. | | E2EE | A security mechanism where a mobile app is coded to only trust a specific, pre-defined key unique for the service provider. With E2EE keys, the app is pinned to a key which is used to secure the communication leveraging both signature validation and encryption. It is an additional layer inside the HTTPS channel to prevent MITM attacks, even at an HTTP root certificates level. It prevents an attack using fraudulent certificates to intercept the communication between the app and the server, isolating data at a service provider level. | ::: ## Benefits of using E2EE Certificate pinning is designed to prevent an attacker from successfully impersonating the server and intercepting traffic. However, a correctly-implemented E2EE application layer means that even if an attacker manages to intercept the connection, the data they capture is useless. :::info Want to learn more? For more information, see our [End-to-end encryption](docs/mobile-identity/mobileid/features/end-to-end-encryption.mdx) feature documentation. ::: ### Analogy To help visualise the concept, you can use the following analogy: - **Certificate Pinning**: You ensure that your letter is delivered by a specific, trusted courier. - **End-to-End Encryption**: You put the letter in a locked safe that only the recipient has the key to. This means that even if the letter is intercepted, it cannot be read. ### Security Our architecture provides the following security guarantees: - **Confidentiality**: All data remains completely private and unreadable to any third party. - **Integrity**: The E2EE mechanism ensures that the data cannot be tampered with in transit. In summary, our application-layer E2EE provides a superior security guarantee compared to certificate pinning by protecting the data itself, not just the channel it travels over. By encrypting data before it even leaves our SDK, we ensure that it remains confidential, regardless of the security of the transport layer. This makes the traditional practice of certificate pinning redundant for our MobileID service. --- ## End-to-end encryption Our end-to-end encryption (E2EE) security mechanism is foundational for MobileID, as all communication between the SDK integrated into your application and our backend servers uses E2EE. ## How does E2EE work? We achieve this using a public-key cryptography system, where a cryptographic key pair consisting of a public and a private key are used to establish a secure channel for all data exchange By encrypting all data with the public key before it leaves the device's memory, we guarantee that the information remains confidential and secure throughout the entire transmission process. :::CustomTable{columnWidths="25% 75%"} | **Key** | **Function** | | :-- | :-- | | Public key | It is distributed and configured within your mobile application. It is used to encrypt data, ensuring that only the holder of the corresponding private key can decrypt it. | | Private key | It is kept secret and secure within our server environment. It is used to decrypt the data sent from the mobile application. | ::: ## Security The always-on E2EE between the SDK and our server provides a robust defence against a wide range of network-based attacks. We encrypt the data at the application layer, which means that the security of the communication channel itself becomes less critical. ### Threat mitigation For some examples of threats that our E2EE security mechanism can mitigate, see the table below: :::CustomTable{columnWidths="25% 75%"} | **Threat mitigated** | **Description** | | :-- | :-- | | Man-in-the-middle (MITM) attacks | An attacker cannot intercept and read the communication, even if they successfully position themselves between your app and our servers. The payload is encrypted and therefore unreadable without the private key. | | Compromised Wi-Fi networks | Devices on unsecured public Wi-Fi networks are protected. An eavesdropper on the same network can only capture encrypted data, not sensitive information. | | Flaws in the transport layer (TLS/SSL) | Although we enforce strict TLS protocols (TLS 1.2 or TLS 1.3 when supported), E2EE provides an additional, independent layer of security. This means that in the unlikely event of a vulnerability being discovered in the TLS implementation, all data remains encrypted and secure. | | Attacks through proxies and VPNs | If a device's traffic is routed through a malicious or compromised proxy server or VPN, the E2EE ensures that the confidentiality of the data is not compromised. | | DNS spoofing | If it was possible for an attacker to redirect your application's traffic to a malicious server, the attack would be ineffective as that server would not have the correct private key to decrypt the E2EE payload. | ::: ## E2EE keys for SDK 3.22 and later Starting with MobileID SDK 3.22, key exchange between the SDK and the server uses the X25519 algorithm. Existing E2EE keys that use the legacy SECT233K1 algorithm are not compatible with SDK 3.22 or later. Before you upgrade your app to SDK 3.22 or later, you must rotate your E2EE key to one that uses the X25519 algorithm. Follow the [key rotation process](#key-rotation) below to avoid downtime. ## Key rotation Key rotation is a critical security practice that limits the potential impact of a compromised key. It involves generating a new public/private key pair and updating your application to use the new public key. Regularly rotating your E2EE keys minimises the risk associated with a key being exposed. If a key was ever compromised, then rotating it would make the old key useless for any future communications, securing the channel once again. ### Rotation Process We have designed the key rotation process to be straightforward and manageable, with no downtime for your application's end-users. To learn how to do this, see the steps below: #### 1. Generate a new key pair 1. Initiate the generation of a new key pair using the [Add E2E key](/apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/addE2EKey) endpoint in the **MobileID Admin API**. This action creates a new public and private key. :::warning Choose the appropriate algorithm The MobileID Admin API uses `X25519` by default when you omit the `algorithm` parameter. Use the legacy value `SECT233K1` only when you generate a key for an app built with an SDK version earlier than 3.22. ::: 2. Once created, the public key becomes available to retrieve from both: - The [Get E2E key](/apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/getE2EKey) endpoint in the **MobileID Admin API** - The **E2E keys** tab on the MobileID [Details](https://dashboard.signicat.com/mobileid/details) page in the Signicat Dashboard. #### 2. Update and distribute your app 1. Configure the Encap controller in your mobile application with the new public key. To learn how to do this, see the: - [Configure the controller](/docs/mobile-identity/encap/sdk-android/getting-started/#configure-the-controller) section on the Android SDK **Getting started** page. - [Configure the controller](/docs/mobile-identity/encap/sdk-ios/getting-started/#configure-the-controller) section on the iOS SDK **Getting started** page 2. Release an updated version of your app to the Apple App Store and Google Play Store. #### 3. Transition period For a period of time, our server accepts data encrypted with both the old and the new public keys. This ensures that end-users who have not yet updated their app can continue to use the service without interruption. #### 4. Revoke the old key Once you are confident that the majority of your end-users have updated to use the latest version of your app, you can revoke the old key using the Signicat Dashboard or the MobileID Admin API. From this point on, only data encrypted with the new key is accepted. --- ## Events (callback) :::info Using our new ReuseID REST API? If you are using MobileID through our new ReuseID API, then see the ReuseID [Events (callback)](/docs/reuseid/events.mdx) documentation instead. ::: Events are our way of letting you know when something happens in one of our services. MobileID events are a type of Signicat event that are specific to the Mobile service. For example, a MobileID event is generated when an authentication result is ready. :::info Learn about Signicat events This page focuses on MobileID events. For general information about Signicat events and the events service, see our [Events and webhooks](/docs/dashboard/settings/events.mdx) documentation. ::: ## How do MobileID events work? When an asynchronous operation completes, or when MobileID gets a notification that a device has changed state, MobileID publishes an event with the operation result. If you have subscribed to the event, then you automatically receive the result at your specified notification URI. This is often referred to as callback. You can also get the operation result back through polling. The result that you receive through the Signicat events service is the same as the result obtained by polling, but wrapped in a Signicat event object. ### When to use callback We recommend that you always set up callback for production. This offers the best usability and responsiveness as it has the least amount of latency, and means that you do not need to conduct additional polling calls. ### When to use polling Regardless of whether callback is set up or not, you can fetch the result of a completed operation from Signicat by polling. You can do this by running GET API calls, but it should only be reserved for testing and development use. ## Which events does MobileID publish? For an overview of the events that you can subscribe to, see the table below: :::CustomTable{columnWidths="25% 15% 60%" tableName="MobileID events"} | **Event name** | `eventName` | **Description** | | :-- | :-- | :-- | | Account recovery | `account-recovery.completed` | When a device operation to perform an account recovery is completed. **Note**: This is a device operation carried out by the end-user. | | Account recovery state change | `account-recovery.state.change` | When a device operation to add or delete account recovery is completed. **Note**: This is a device operation carried out by the end-user. | | Authentication | `authentication.completed` | When an operation to authenticate with MobileID is completed. | | Device state change | `device.state.change` | When an operation to change the state of a MobileID device is completed. **Note**: This is a device operation that happens when the device is locked or deactivated by an external action. For example: The device can be **locked** if the end-user enters an incorrect PIN too many times in a row. The device can be **deactivated** by the device SDK. The device can be **deactivated** by the periodic cleanup job if the device has been inactive for too long, such as one year. | | Registration | `registration.completed` | When an operation to register a new MobileID device is completed. | | Signature | `signature.completed` | When an operation to sign with MobileID is completed. | ::: ## What do MobileID events look like? Events follow the same structure across all Signicat services, with the exception of the event data (`eventData`) field. This field varies depending on the type of event, as it is where we pass the operation result as a JSON object. You can find an overview of a MobileID event in the table below: :::CustomTable{columnWidths="25% 40% 15% 20%" tableName="MobileID event structure"} | **Field name** | **Description** | **Type** | **Example** | | :-- | :-- | :-- | :-- | | `id` | The ID of the event. | String | `13a816b4-f6f3-4424-907c-a95e234155b2` | | `timestamp` | The timestamp when the event was created. | ISO 8601 date string | `2024-07-02T12:53:13.659Z` | | `eventName` | The name of the event. | String | `registration.completed` | | `sender` | The service which is sending the event | String | `mobileid` | | `eventData` | The event data. | JSON | _JSON object with event data._ | | `accountId` | The account ID which the event is sent in the context of. | String | `a-ppge-abcdefeghijklmn12345` | | `expiresAt` | The timestamp when the event expires. **Note**: There are no more retries after this timestamp. | ISO 8601 date string | `2024-07-02T12:58:13Z` | | `tags` | Optional tags that can be included in the event. **Note**: You add tags by setting them in the request to the service publishing the events. | String array | _Empty list._ | ::: ## How to subscribe to MobileID events You can use the Signicat Dashboard to subscribe to the events that you would like to receive callback for. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Events**](https://dashboard.signicat.com/events). 2. Click the **+Add subscription** button. 3. Select a subscription type, for example **Webhook**. 4. Complete the required fields. In the **Listen to** section, under **MobileID**, select the events that you want to subscribe to. 5. Click the **Add** button. :::info Want to learn more? To learn more about subscribing to and managing events, see the [Events and webhooks](/docs/dashboard/settings/events.mdx) page in the Signicat **Dashboard** documentation. ::: ## How to preview MobileID events You can preview what the JSON payload looks like for each event in the Signicat Dashboard when you set up a new subscription. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Events**](https://dashboard.signicat.com/events). 2. Click the **+Add subscription** button. 3. Select a subscription type, for example **Webhook**. 4. Under the **Listen to** section, click **Selected events**, then expand the **MobileID** dropdown menu. 5. Hover over the event that you want to preview, then click the **Preview** button that appears to the right of the event name. 6. An example of the event appears to the right-hand side of the screen. You can use the **Example** toggle button at the top of the example to toggle between the operation result and the entire Signicat event object. :::tip What do the properties in the example mean? To learn what the different properties mean in the examples, see the respective response schema in the [MobileID API reference](pathname:///apis/mobileid/) documentation. --- ## Face authentication(Features) ## About face authentication Our face authentication feature is an authentication method that uses server-side biometrics. Server-side biometrics are authentication methods that are independent of the device. This means that they can offer cross-device compatibility and centralised management. The face authentication method performs a two-second facial scan with **3D Liveness Check** and **3D Face Matching** on each authentication. This is done within a mobile app and verified on the server, preventing unauthorised access to an account. ### What is a 3D Liveness Check? A **Liveness Check** (also referred to as liveness detection) means that we will verify that it is a physical human in front of the device. We ensure that it is not a photo, deepfake video, or similar spoofing tool. :::info Want to learn more? To learn more about biometric liveness detection, see the [liveness.com](https://www.liveness.com/) web page. ::: ### What is 3D Face Matching? A 3D Face Matching means that we will verify that the human performing the authentication is the same as the one who activated face authentication initially. To do this: 1. At the time of authentication, a **3D FaceMap** is collected together with the liveness data. 2. We match this 3D FaceMap to the 3D FaceMap that we collected during the activation of this authentication method. ### Example use cases - You want to implement additional fraud prevention for high-risk transactions, by verifying that the end-user performing the transaction is a real person and the same as the one who activated. - You want your end-users to be able to recover with biometric authentication on a new device. - You want your end-users to be able to reset their authentication credentials. - You want to have multiple end-users performing biometric authentications on the same device. ### What is the difference between Face ID and face authentication? Face ID is a type of native biometrics, whereas face authentication is a type of server-side biometrics. You can read about what these mean in the sections below: #### Native biometrics Native biometrics are authentication methods provided by the device's operating system, executed and validated directly on the device for quick and secure authentication using the device's hardware and software. Some examples of native biometrics are Apple Face ID, Apple Touch ID and Android BiometricPrompt. :::tip Our recommendation Native biometrics are fast, secure, and offer a great user experience. We recommend using native biometrics whenever possible. ::: #### Server-side biometrics Server-side biometrics are authentication methods that are independent of the device. These methods offer cross-device compatibility and centralised management, which means that they can be leveraged in some [use cases](#example-use-cases) where native biometrics will not work. An example of server-side biometrics is our face authentication feature. #### When are server-side biometrics a good option? There are some use cases where native biometrics will not work, or where server-side biometrics can provide a better option. For example: - When your end-users have invalidated their native biometrics. - When your end-users want to securely reset their authentication credentials. - When you want to recover your end-user's account, if: - Their device has been lost, broken or stolen. - They have deleted your application. - When multiple end-users want to use biometrics on the same device. - When the end-user wants to use another device. - Prevent phishing attacks when your end-users onboard. - Provide additional fraud prevention for high-risk transactions, such as verifying that the activated end-user is present at the time of the transaction. ## How does face authentication work? As with all other authentication methods, face authentication needs to be activated before end-users can start using it. Once you have activated face authentication for your end-users, you can use it to: - Authenticate [(see section on this page)](#how-to-authenticate-with-face-authentication) - Perform account recoveries [(see section on this page)](#how-to-recover-with-face-authentication) - [Reset authentication credentials](/docs/mobile-identity/mobileid/use-cases/reset-authentication-credentials.mdx) - [Prevent identity fraud](/docs/mobile-identity/mobileid/use-cases/identity-fraud-prevention.mdx) :::note Quotas Activation and authentication operations using face authentication are subject to quota limits. For default quotas and more information, see the [Quotas](#quotas) section. ::: ### Basic flow for a face authentication 1. A FaceMap is captured on the end-user's device. 2. The captured FaceMap is securely transmitted to our server. 3. The server processes and validates the FaceMap, performing the necessary authentication checks. ### How to activate face authentication To activate face authentication, you first need to register a device for your end-user. Once the user has an active device, you can then add face authentication using our `addOrUpdate` method in the SDK. You can learn how to do this in the **Add or update** sections of our SDK documentation: * [**Add or update for Android**](/docs/mobile-identity/encap/sdk-android/core-operations/#add-or-update): Learn how to activate a device for face authentication with the Android SDK * [**Add or update for iOS**](/docs/mobile-identity/encap/sdk-ios/core-operations/#add-or-update): Learn how to activate a device for face authentication with the iOS SDK #### What does an activation look like? The following diagram illustrates what it could look like to activate face authentication with MobileID, from the perspective of your end-users. Diagram showing end-user flow for activating face authentication #### Diagram for activation The following sequence diagram illustrates an activation of face authentication. Sequence diagram showing activation of face authentication ### How to authenticate with face authentication You can initiate a face authentication by setting `FaceAuthentication` as the `authMethod` when you start the authentication operation. See the [Start authentication](pathname:///apis/reuseid/#tag/MobileID-Authentication/operation/addAuthentication) endpoint in the ReuseID API reference documentation for details. #### What does an authentication look like? The following diagram illustrates what it could look like to authenticate with face authentication in MobileID, from the perspective of your end-users. Diagram showing end-user flow for authentication with face authentication #### Diagram for authentication The following sequence diagram illustrates an authentication with face authentication. Sequence diagram showing authentication with face authentication ### How to recover with face authentication Our account recovery feature supports server-side face authentication as an authentication method. We recommend this for recovery, as: - It is more user-friendly, with no recovery code to remember. - It enhances security by not having a recovery code which could be shared. To learn about this feature and how to implement it, see our [Account recovery](/docs/mobile-identity/mobileid/features/account-recovery.mdx) feature documentation. ## How to configure face authentication To use our face authentication feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK Learn how to configure the mobile SDK for face authentication using the SDK guides below: * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/face-authentication): Learn how to configure the Android SDK for face authentication * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/face-authentication): Learn how to configure the iOS SDK for face authentication ### Configure the application configuration You do not need to make any changes to the application configuration to use our face authentication feature, as by default: - Our face authentication feature is enabled for use by the server. - Server-side face is enabled as an allowed authentication method. #### Enable/disable as an allowed authentication method You can determine whether or not the server-side face authentication method is allowed for use in operations. To do this: 1. Log in to the Signicat Dashboard. 2. Go to **Products** > **MobileID** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour), then select the **Authentication tab**. 3. Use the check boxes to enable or disable server-side face as an authentication method. :::tip Tip To disable server-side face in the **Allowed authentication methods** section, you must first disable it in the **Allowed authentication methods when activating new method or changing PIN** section. ::: ## Quotas All performed activation and authentication operations which use face authentication are subject to the default quota limits. If your app exceeds the default quotas outlined in the tables below, then your requests may fail. To update the quota limits, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### Production environment Default quotas in the production environment: | **Quota name** | **Default limit** | | :-- | :-- | | `Face authentications per account per day` | `1000` | | `Face authentications per account per minute` | `10` | | `Face registrations per account per day` | `1000` | | `Face registrations per account per minute` | `10` | ### Sandbox environment Default quotas in the sandbox environment: | **Quota name** | **Default limit** | | :-- | :-- | | `Face authentications per account per day` | `100` | | `Face authentications per account per minute` | `10` | | `Face registrations per account per day` | `100` | | `Face registrations per account per minute` | `10` | ## Try it out To test our face authentication feature on a mobile device, you need to add the SDK to your app. To get access to the SDK, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Geofencing(Features) ## About geofencing Our geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. By limiting the use of registrations and authentications to certain regions, you can reduce the chance of fraud. ### Example use case You want to be notified of transactions that occur in a specific country. This means that if someone tries to register or authenticate in this country, then you can either block the transaction or be notified that it is happening. ## How does geofencing work? When geofencing is enabled, the SDK will send the country code of the location of the device to the MobileID service. The MobileID service will verify the location and limit the use of the device based on the configuration in your application configuration and what you have set as your allowed regions. ### What are allowed regions? Geofencing allowed regions are defined as: > **allowed continents** + **allowed countries** - **denied countries** ### How are countries and continents defined? Countries are identified in an ISO 3166-1 alpha-2 two-letter country code format. Geofencing regions can also be defined on continent level. In this instance, the MobileID service maps between the SDK country and its associated continent. The MobileID service contains a default mapping which is defined according to ISO 3166 and the data from [GeoNames.org](https://download.geonames.org/export/dump/countryInfo.txt). ### Basic flow for geofencing 1. The MobileID service informs the SDK about the current geofencing mode. 2. Depending on the geofencing mode, the SDK determines whether to call the external geocoder platform service with location as a parameter. 3. If the external geocoder platform service was called, then it will return the address from the location. 4. The SDK sends the country from the address to the MobileID service. :::tip Note The region must be allowed in the application configuration and the end-user must grant location permissions to the SDK. ::: 5. When the transaction completes, the MobileID service will evaluate if the country reported by the SDK is within the allowed regions, according to the following rule: ```java if (country in && clientCountry not in || country in ) { // Success } else { // Failure - deny reject transaction (if REQUIRED mode) } ``` 6. If the transaction was performed by a mobile SDK outside of the allowed geofencing boundaries, then the result depends on which mode you have configured geofencing to use: - If geofencing is set to the `REQUIRED` mode, then the transaction will fail. - If geofencing is set to the `OPTIONAL` mode, then the transaction will succeed, but the result of the evaluation is reported to you together with the actual country. It is up to you what action to take on the result. ### Risks - For iOS, with a compromised system such as a jailbroken device, it is possible to fake the location that is coming from the platform's location API. - For Android, it is possible to install a location provider that can fake your location. This can be done without rooting the device. To help mitigate these risks, you can shield the app or implement app attestation. ## API integration ### Geofencing result object The result of the geofencing validation is returned in the registration, authentication and signature operation responses as the `geofencing` object. :::CustomTable{columnWidths="25% 75%"} | **Field** | **Description** | | :-- | :-- | | `countryCode` | The country code in an ISO 3166-1 Alpha-2 format, as reported by the SDK. | | `clientStatus` | The status of the geofencing operation, as reported by the SDK. See [Geofencing client status](pathname:///apis/reuseid/#section/Common-concepts/Geofencing-client-statuses) for possible values. | | `serverBoundaryValidation` | The status of the geofencing server validation, after evaluating the country against the allowed region. See [Geofencing server boundary validation statuses](pathname:///apis/reuseid/#section/Common-concepts/Geofencing-server-boundary-validation-statuses) for possible values. | ::: :::tip Geofencing client status If a country code is obtained successfully, then the geofencing client status field (`clientStatus`) will be populated with `OK`. If the device fails to obtain a location, or if the SDK's reverse geocode request fails, then the `clientStatus` field will be populated with an appropriate status. ::: **Example: Geofencing result object** ```json "geofencing" : { "countryCode" : "NO", "clientStatus" : "OK", "serverBoundaryValidation" : "SUCCESS" } ``` ### Override configuration for a specific device For authentication operations, you can modify the geofencing configuration for a specific device using our REST APIs. This will override the geofencing configuration in the application configuration. #### Get geofencing configuration for a device To retrieve the geofencing configuration for a given device, you can use the [Get geofencing settings](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/getGeofencingSettings) endpoint in our ReuseID API. As a result, the geofencing configuration object is returned. #### Update geofencing configuration for a device To update the geofencing configuration for a given device, you can use the [Update geofencing settings](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/putGeofencingSettings) endpoint in our ReuseID API. As a result, the geofencing configuration object is returned. #### Delete geofencing configuration for a device To delete the geofencing configuration for a given device, you can use the [Delete geofencing settings](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/deleteGeofencingSettings) endpoint in our ReuseID API. ## How to configure geofencing To use our geofencing feature, you need to: - [Configure the mobile SDK](#configure-the-mobile-sdk). - [Configure the application configuration](#configure-the-application-configuration). ### Configure the mobile SDK You can use the buttons below to learn how to configure the mobile SDK for geofencing. * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/geofencing): Learn how to configure the Android SDK for geofencing. * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/geofencing): Learn how to configure the iOS SDK for geofencing. ### Configure the application configuration To enable and configure geofencing, you need to update your application configuration. You can see what values need to be set in the [Geofencing](/docs/mobile-identity/mobileid/features/application-configuration/#geofencing) section in the **Application configuration** feature documentation. :::tip About geofencing configurations The configuration is split into a set of properties for registration and authentication, so that you can enforce different rules for the different operations. ::: To find out how to set these properties, see the [Make changes to your configuration](#make-changes-to-your-configuration) section on this page. #### Geofencing modes The geofencing feature can be used in multiple modes: :::note OFF The `OFF` mode means that a device location check is not performed. By default, geofencing is always turned `OFF`. ::: :::note OPTIONAL The `OPTIONAL` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will still be performed. It is up to you what action is taken on the result. ::: :::note REQUIRED The `REQUIRED` mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will fail. ::: #### Make changes to your configuration To update your application configuration with the necessary properties, you can use the [Signicat Dashboard](https://dashboard.signicat.com/mobileid/features/geofencing). --- ## How it works(Hardware-protected-keys) Hardware-protected keys are stored in hardware, typically in a trusted execution environment (TEE) or on a trusted platform module (TPM), and will never leave it. As a result, all operations that require the private key are performed in the secure hardware on the device. Even rooted devices safeguard hardware-protected keys from extraction, as these keys cannot be cloned. ## Activation The usual flow for activation of a hardware-protected key is as follows: 1. The MobileID client SDK generates a key pair in the secure hardware. 2. The secure hardware returns the public hardware-protected key to the MobileID client SDK. 3. The MobileID client SDK returns this key to the MobileID server over the secure channel in the `finish activation` request. 4. The MobileID server stores the public hardware-protected key on the registration, and this key will be used to verify all future authentications. ```mermaid sequenceDiagram participant SDK as MobileID client SDK participant HW as Secure hardware participant Server as MobileID server SDK->>HW: Generate key pair HW-->>SDK: Return public hardware-protected key SDK->>Server: Send key in finish activation request Server->>Server: Store public key for future verification ``` ## Authentication For devices activated with hardware-protected keys, an additional security check is conducted during every authentication. The MobileID server is used to validate the hardware signature. The usual flow for authentication with hardware-protected keys is as follows: 1. The MobileID client SDK will sign the authentication challenge, received from the MobileID server in the `start authentication` request, with the hardware-protected private key. 2. The signed challenge is passed back to the MobileID server in the `finish authentication` request over the secure channel. 3. The signed challenge is verified server-side with the hardware-protected public key. ```mermaid sequenceDiagram participant Server as MobileID server participant SDK as MobileID client SDK participant HW as Secure hardware Server->>SDK: Send challenge in start authentication request SDK->>HW: Sign challenge with private key HW-->>SDK: Return signed challenge SDK->>Server: Send signed challenge in finish authentication request Server->>Server: Verify signature with stored public key ``` ## Supported devices Hardware-protected keys are supported on the following devices: - Android 6 (most devices) - Android 7 or later (all devices) - iOS 10 or later (devices with [Secure Enclave](https://support.apple.com/en-au/guide/security/sec59b0b31ff/web)) :::note Note Devices that do not support hardware-protected keys will only use software keys. ::: --- ## Hardware-protected keys(Hardware-protected-keys) Our hardware-protected keys feature enables you to strengthen proof-of-possession and maximise device security. This feature can be used in addition to dynamically-generated software keys. ## Use cases Hardware-protected keys make it highly improbable that an attacker can extract the keys stored in the device's secure hardware and use them externally, without physically compromising the device. ## Get started * [**How it works**](/docs/mobile-identity/mobileid/features/hardware-protected-keys/how-it-works): Learn about what hardware-protected keys are and how they work * [**Set it up**](/docs/mobile-identity/mobileid/features/hardware-protected-keys/set-it-up): Learn about how to set up hardware-protected keys --- ## Set it up(Hardware-protected-keys) Support for hardware-protected keys is enabled by default. The hardware-protected key validation strategy determines what to do with devices if the validation for hardware-protected keys fails. This can be configured in your application configuration using the `hwKeyValidationStrategy` property. ## Validation strategies There are two validation strategies that you can choose between, shown in the table below: :::CustomTable{columnWidths="25% 75%"} | **Validation strategy** | **Description** | | :-- | :-- | | `REQUIRED_IF_SUPPORTED` | Enforces hardware key validation if the device supports hardware keys.Activations and authentications will fail if a hardware key is registered but the provided signature is invalid.**Note**: This is the default strategy. Devices lacking hardware support are permitted to proceed with the operation. | | `REQUIRED` | Enforces hardware key validation for all devices.Activations and authentications will fail if the client cannot generate a hardware-supported key, or fails to provide a valid signature from it. | ::: ## Update your configuration To update your application configuration, you can use the [Update properties of application configuration](pathname:///apis/mobileid-admin/#tag/Application-configuration/operation/updateAppConfigurationProperties) endpoint in our **MobileID Admin API**. With this operation, you can set a new value for the `hwKeyValidationStrategy` property, depending on your chosen validation strategy. ## Validation result The result of the hardware signature validation can be collected and returned in the operation response, as a part of the following risk attributes: | **Attribute name** | **Possible values** | | :-- | :-- | | `hwKeyClientStatus` | [Hardware-protected key client statuses](pathname:///apis/reuseid/#section/Common-concepts/Hardware-protected-key-client-statuses) | | `hwKeyServerResult` | [Hardware-protected key server results](pathname:///apis/reuseid/#section/Common-concepts/Hardware-protected-key-server-results) | ### Enable risk attributes The hardware-protected key risk attributes are **Optionally collected**, which means that they are not collected and returned in the operation response by default. To enable these risk attributes, you need to set them in our risk data feature: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > **Features** > [**Risk data**](https://dashboard.signicat.com/mobileid/features/risk-data/). 2. Under the **Optionally collected** section, tick the following: - **Hardware key client status** - **Hardware key server result** 3. Click the **Save** button. --- ## Features(Features) You can learn about MobileID features in our feature guides. * [**Account recovery**](/docs/mobile-identity/mobileid/features/account-recovery): Allow your end-user to recover their authentication credentials using two-factor authentication * [**App attestation**](/docs/mobile-identity/mobileid/features/app-attestation): Strengthen your application's security by preventing third-party use of our APIs * [**App security**](/docs/mobile-identity/mobileid/features/app-security): Provide proactive security for your app against a wide range of attacks * [**Application configuration**](/docs/mobile-identity/mobileid/features/application-configuration): Configure attributes that determine how the mobile application should work * [**Broadcast**](/docs/mobile-identity/mobileid/features/broadcast): Broadcast authentication and signing operations to all of your end-user's active devices * [**Certificate pinning**](/docs/mobile-identity/mobileid/features/certificate-pinning): Ensure that your app only communicates with a trusted backend * [**End-to-end encryption**](/docs/mobile-identity/mobileid/features/end-to-end-encryption): Ensure that data in transit cannot be tampered with using application-layer E2EE * [**Events (callback)**](/docs/mobile-identity/mobileid/features/events): Automatically receive the result of a completed operation at a specified notification URI * [**Face authentication**](/docs/mobile-identity/mobileid/features/face-authentication): Authenticate your end-users with face authentication across devices * [**Geofencing**](/docs/mobile-identity/mobileid/features/geofencing): Reduce fraud by limiting the use of your app to certain regions * [**Hardware-protected keys**](/docs/mobile-identity/mobileid/features/hardware-protected-keys): Strengthen proof-of-possession and maximise device security * [**Multi-registration**](/docs/mobile-identity/mobileid/features/multi-registration): Activate multiple registrations within one mobile application * [**Operation context**](/docs/mobile-identity/mobileid/features/operation-context): Send important information to your app, through our secure channel * [**Push notifications**](/docs/mobile-identity/mobileid/features/push-notifications/): Inform the end-user that something is happening in your app that requires their attention * [**Risk indicators**](/docs/mobile-identity/mobileid/features/risk-indicators): Flag suspicious events that may indicate malicious intent * [**Signature**](/docs/mobile-identity/mobileid/features/signature): Authentication that also returns a signed JWT containing all transaction data --- ## Multi-registration(Features) ## About multi-registration Our multi-registration feature allows you to activate and manage multiple independent registrations within a single mobile app. This is useful for apps that need to support multiple end-user accounts or identities concurrently. Diagram showing multi-registration use case ### Example use cases - Multiple end-users share the same mobile device, and each person needs to securely access their own account within the app. For example, this could be the case with family or colleagues sharing the same tablet. - An end-user has multiple accounts with separate authentication credentials for each, which they need to access on the same mobile device. For example, this could be the case if the end-user has a personal account and a business account. ## How does multi-registration work? To use multi-registration, you must create multiple controllers within the SDK, where each controller corresponds to a unique registration. When you create a new controller for a multi-registration app, you need to give the controller a unique name. This name is then later used to identify the controller. ### Handling push notifications When you use our multi-registration feature, you may need to make considerations about how push notifications are handled. A push notification indicates to the end-user that something is happening for one of the registrations in the app that requires attention, however: - There is no information in the push message that indicates for which registration the push was triggered. - The app does not know what controller to start the authentication for. To handle this in your app, there are two alternatives: #### Send information in the push payload When you start an authentication, you have the option to set a `pushPayload` which is passed in the push notification. You can use this to give the app information about what controller to use. :::warning Important The push payload is not a secure channel. This means that you should not use it to share sensitive information such as secrets. ::: #### Verify on all controllers When your end-user opens the app, start with iterating through all of controllers. You can run a `startAuthentication` to check if there is any ongoing activity for that registration. ## How to implement multi-registration To use our multi-registration feature, you only need to create multiple named controllers within the SDK; no additional configuration is required. The process for creating a controller is different for Android and iOS. ### Android To create a new controller with a unique name on Android: ```kotlin title="Example: Create a named controller for Android" Controller controller = AndroidControllerFactory.getInstance(androidContext, "registrationA"); ``` ### iOS To initialise the `EncapController` with a unique name on iOS: ```swift title="Example: Create a named controller for iOS" let controller = EncapController(name: "registrationA") ``` --- ## Operation context(Features) ## About operation context MobileID supports a **pre-operation context** and a **post-operation context** for each operation. This feature allows you to send important information to your app, through a secure channel with end-to-end encryption (E2EE). This information can be passed: - Before the operation has been approved (pre-operation context). - After the operation has been successfully completed (post-operation context). ### Example use cases - Ask the end-user for approval of an operation, such as when the operation is initiated in a different channel to your application. - Conduct PSD2 RTS-compliant payment transactions. - Share sensitive information such as a PIN or access token with your application, that you **only** want to be available on the device after a successful operation. ## How does operation context work? The operation context contains a content (`content`), which is a binary blob. The content has a MIME type (`mimeType`), so your app can determine how to process the content. The operation context is specified when you're initiating a device operation. The context is passed from our MobileID backend to our SDK, and then to your application through our secure channel using E2EE. ### Types of operation context We support two types of operation context: :::CustomTable{columnWidths="25% 75%"} | **Object name** | **Description** | | :-- | :-- | | `preOperationContext` | Context sent to the app, across our secure channel using E2EE, **before** the operation is approved. | | `postOperationContext` | Context sent to the app, across our secure channel using E2EE, **only after** a successful operation. | ::: ### Encrypted channel In addition to the Transport Level Security (TLS) that our MobileID backend and SDK utilises for all communication, we also leverage an additional E2EE layer inside the TLS channel to further protect the information in your operation context. We achieve this by including a crypto library within the SDK, and using this to establish an E2EE channel between our MobileID backend and SDK. This protects against: - Instances when malware on the device is manipulating the platform crypto libraries. - Man-in-the-middle (MITM) cyberattacks on the device. ## Pre-operation context The pre-operation context is sent from our MobileID backend to the SDK **before** the user has completed the authentication. This means that you can use the pre-operation context to share information with your application that you want to be available on the device **before** the operation has been approved. The SDK then passes the pre-operation context back to the application, and then it is up to the application to either display the information in an appropriate way, or use the data without sharing it with the end-user. **Example 1: Use case for pre-operation context** You can use the pre-operation context to ask the end-user for approval of an operation, when it is initiated in a different channel to your application. :::note Operation context shown to end-user "Do you want to log in to **www.example.com** in Safari, on Jane's MacBook Pro?" ::: **Example 2: Use case for pre-operation context** You can use the pre-operation context to execute a PSD2 payment transaction. To do this, you must pass the transaction amount and the recipient details as part of the pre-operation context. This is required for [PSD2 Dynamic Linking](#about-psd2-dynamic-linking). :::note Operation context shown to end-user "Do you want to transfer $300 to Jane Smith?" ::: Diagram showing example of pre-operation context in PSD2-compliant transaction ### About PSD2 Dynamic Linking Our product is PSD2 RTS-compliant and can be used for payment transactions. For payment transactions, you need to pass the transaction amount and the recipient details as part of the pre-operation context. The Dynamic Linking requirement of the PSD2 RTS is supported in our strong customer authentication (SCA). This is done by cryptographically binding a unique authentication code generated by our server, to the pre-operation context shared by you to the transaction. This provides non-repudiation for the transaction. If somebody manipulates the pre-operation context, then the operation will fail. **Sequence diagram: Pre-operation context** Sequence diagram illustrating pre-operation context being used for a PSD2-compliant transaction. Sequence diagram showing PSD2-compliant transaction ## Post-operation context The post-operation context is only sent from our MobileID backend to the SDK **after** an operation has been successfully completed. This means that you can use the post-operation context to share sensitive information with your application that you want to be available on the device **after** a successful operation. After an operation has been successfully approved, we pass the post-operation context back to the application. It is then up to the application to either display the information in an appropriate way, or use the data without sharing it with the end-user. **Example 1: Use case for post-operation context** You can use the post-operation context to send a new PIN to the end-user. :::note Operation context shown to end-user "Your new Visa card PIN is 349283." ::: Diagram showing example of post-operation context used to send new PIN **Example 2: Use case for post-operation context** You can use the post-operation context to share information or data that is required for the application to communicate with your backend, such as an access token. **Sequence diagram: Post-operation context** Sequence diagram illustrating post-operation context being used to share an access token with the app. Sequence diagram showing post-operation context used to share an access token with app ## Configuration options You can configure operation context for any of the device operations. :::tip Note For registration operations, only post-operation context is supported. ::: ### Operation context object The `preOperationContext` and `postOperationContext` objects are made up of 3 fields: :::CustomTable{columnWidths="25% 75%"} | **Field name** | **Description** | | :-- | :-- | | `title` | The title of the context. | | `content` | The content of the context. **Note**: MobileID handles this as a binary blob. | | `mimeType` | The MIME type of the content. **Note**: Must be a valid MIME type. | ::: The content of the operation context object can be any MIME type that your application is able to process. For example, you could: - Pass a string in the content that you want to show to the user in the app, using `text/plain` as the MIME type. - Pass a PDF document in the content that you want to show to the user in the app, using `application/pdf` as the MIME type. - Pass JSON formatted strings that the app parses and uses for application control or user navigation, using `application/json` as the MIME type. You need to provide the operation context when you initiate an operation. See **MobileID device authentication** and **MobileID device registration** in our [ReuseID API reference documentation](pathname:///apis/reuseid/) for more details on how to do this. --- ## Create APNs token(3) For iOS, we use Apple Push Notification service (APNs) to send push notifications. To be able to use this, you need to create an APNs token for your application: ## 1. Create an APNs provider authentication token 1. Log in to the [Apple Developer Program Portal](https://developer.apple.com/account/). 2. Go to **Certificates, Identifiers & Profiles**. 3. From the left-side menu, select **Keys**. Next, click the **+** button to register a new key. 4. Add a **Key Name** and optionally a **Key Usage Description**. 5. Tick the **ENABLE** box for **Apple Push Notifications service (APNs)**, then click the **Configure** button. 6. In the **Environment** dropdown menu, select the desired option, then click the **Save** button. 7. Click the **Continue** button, then click the **Register** button. 8. Copy the displayed Key ID (`KeyID`) and store it in a secure place. 9. Click the **Download** button to download `.p8` file containing the token, then store it in a secure place. ## 2. Find your Team ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Membership details**. 2. Copy the **Team ID** and store it in a secure place. ## 3. Find your Bundle ID 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the application that you are configuring the APNs token for. 4. Copy the **Bundle ID** and store it in a secure place. ## 4. Add to enabled capabilities You need to add push notifications as enabled capabilities for the provisioning profile when you are publishing your app. To do this: 1. In the [Apple Developer Program Portal](https://developer.apple.com/account/), click **Program resources**. 2. Under the **Certificates, Identifiers & Profiles** section, click **Identifiers**. 3. Select the App ID that you want to update, then click **Edit**. 4. Select the checkbox to enable push notifications. :::tip Tip You can also enable any other app capabilities that you want to allow, such as time-sensitive notifications. To learn more about this, see the [Time-sensitive notifications](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications/#time-sensitive-notifications) section in our iOS SDK **Push notifications** documentation. ::: 5. Click the **Save** button. :::note Note If a warning dialogue box appears, then click the **Confirm** button to finalise your changes. ::: --- ## Create Firebase project(3) For Android, we use Firebase Cloud Messaging (FCM) to send push notifications. To be able to use this, you need to create a Firebase project for your application: ## 1. Create a new Firebase project You need to create a Firebase project so that you can download the push configuration file for the Android platform. To do this: 1. Log in to the [Firebase Console](https://console.firebase.google.com/u/0/) with your Google account. If you do not have one, then you can create a Google account for free. 2. On the Firebase Console home page, click the **Add project** button. 3. Enter a project name. This name should be relevant to your name or business. 4. **Optional**: Choose whether to enable Google Analytics for your project. This is not a requirement, but can be enabled at this point if you want analytics tracking. 5. Click the **Create project** button, then click **Continue**. ## 2. Download the push configuration file You must generate the platform-specific configuration file that links your app to Firebase services. This configuration file is necessary to enable push notifications. To do this: 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **General** tab, then scroll down to the **Your Apps** section. 3. Click the **Add app** button, then select the **Android** platform. 4. Enter your Android app's package name. :::tip Tip You can also add a nickname for the app and specify the SHA-1 if required. The SHA-1 is optional for push notifications, but may be required for other Firebase services. ::: 5. Click the **Register app** button. 6. Download the `google-services.json` configuration file and store it in a secure place. 7. Skip the next steps, then click the **Continue to console** button. ## 3. Create the service account key 1. In the left-side menu of your Firebase project dashboard, click the **Settings** gear icon, then select **Project Settings**. 2. Select the **Service accounts** tab and click the Google Cloud link for **All service accounts**. This will open the Google Cloud Project associated with your Firebase project. 3. In the left-side menu click on **Service Accounts** 4. With Firebase Admin SDK selected, press **Generate new private key**. 5. When the new `.json` key file is downloaded, ensure that you store it in a secure place. --- ## Push notifications(4) ## About push notifications Our push notifications feature enables you to inform the end-user that something is happening in your app that requires their attention. This is an optional feature that you can configure in the application configuration. If you enable push, you can also toggle it when initiating the authentication. :::note Note Push notifications can be used to improve the end-user experience, but you are not required to use them. They have no impact on the authentication operation itself. ::: ### Example use cases - You want to notify your end-users who are attempting to log in to your website that they have a login request to approve. - You want to notify your end-user on their mobile device that they have a transaction to authorise. ## How to implement push notifications To implement our push notifications feature, you need to: - [Configure the application configuration](#configure-the-application-configuration). - [Configure the mobile SDK](#configure-the-mobile-sdk). ### Configure the application configuration To use push notifications, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to receive push notifications. #### Prerequisites Before you start, you need to create an APNs token (iOS) and set up a Firebase project (Android). To learn how to do this, use the buttons below: * [**Android prerequisites**](/docs/mobile-identity/mobileid/features/push-notifications/create-firebase-project): Learn how to create a Firebase project for your app * [**iOS prerequisites**](/docs/mobile-identity/mobileid/features/push-notifications/create-apns-token): Learn how to create an APNs token for your app #### Configure push notifications Once you have completed the prerequisites, you can configure your app to use push notifications. :::warning Configure Android and iOS simultaneously Currently, you need to configure push notifications for Android and iOS simultaneously. ::: To start, go to **Signicat Dashboard** > **Products** > **MobileID** > **Features** > [**Push**](https://dashboard.signicat.com/mobileid/features/push). ##### 1. Add APNs token You need to add the APNs token using the values obtained when you created it in the Apple Developer Program Portal. To do this: 1. Select the **APN tokens** tab. 2. Click the **+ Add new** button. 3. Add the following values to the fields in the dialogue box: | **Field name** | **Description** | | :-- | :-- | | Name | Give the APNs token a name. | | Description | Give the APNs token a description. | | Key ID | Add the Key ID that you obtained when you created the token. | | Team ID | Add your Team ID that you obtained from **Membership details**. | | Private key | Add the private key from the `.p8` file that you downloaded when you created the token.

**Note**: You can open the `.p8` file using a text editor app. | 4. Click the **Add** button. :::tip Tip An APNs token can be used by all accounts in the same organisation. ::: ##### 2. Enable push notifications You need to enable and configure push notifications in your application configuration. To do this: 1. Select the **Configuration** tab. 2. Use the toggle button to enable push notifications. Once enabled, additional options that you can use to configure push notifications become available. 3. To configure APNs: 1. Select the APNs token that you created. 2. Add the Bundle ID that you obtained from **Identifiers** in the prerequisite step. 4. To configure Firebase, add the contents of the `.json` key file obtained in the prerequisite step to the **Firebase service account** field. 4. Once you have finalised configuring push notifications, click the **Save** button. :::info Want to learn more? To learn more about the configurable properties, see the [Push notifications](/docs/mobile-identity/mobileid/features/application-configuration/#push-notifications) section in our **Application configuration** feature documentation. ::: ### Configure the mobile SDK You must also configure the SDK for push notifications. To learn how to do this, read the platform-specific documentation using the buttons below: * [**Configure the Android SDK**](/docs/mobile-identity/encap/sdk-android/configure-features/push-notifications): Learn how to configure the Android SDK for push notifications * [**Configure the iOS SDK**](/docs/mobile-identity/encap/sdk-ios/configure-features/push-notifications): Learn how to configure the iOS SDK for push notifications --- ## Device hash(Risk-indicators) The **device hash** risk indicator allows you to identify and manage MobileID devices associated with a single physical device. By correlating seemingly unrelated users to a single device, you can proactively detect and prevent fraud attempts, such as account takeovers. ## How it works During the MobileID registration of a new device, the client SDK automatically generates a unique device hash (`deviceHash`). This hash remains consistent for the physical device, even if your application is uninstalled and reinstalled. By monitoring the `deviceHash` across your user base, we can identify anomalies. :::tip Example For example, if a single device hash is suddenly tied to an unusually high number of users, it could strongly indicate that a bad actor is using one device to cycle through compromised accounts. ::: ### What is a device hash? A device hash is designed to be a unique and persistent digital fingerprint which can be used to identify a specific mobile device within your app. It is a SHA-256 hash of the unique ID generated for the device: - For Android, this unique ID is derived from the `Settings.Secure.ANDROID_ID` value in the Android SDK. - For iOS, this unique ID is generated by the SDK using Apple's `CFUUIDCreate` function and stored in the end-user's iCloud Keychain. ## Configuration options You can configure the following parameters for the device hash risk indicator: | **Parameter** | **Description** | | :-- | :-- | | Allowed number of users with same device hash | The number of users that can be associated with a single device hash before it is flagged as suspicious. The default value is `2`. | To update the configuration, you can use the [**Update device hash configuration**](pathname:///apis/mobileid-admin/#tag/Risk-indicators-configuration/operation/updateRiskIndicators) endpoint in the MobileID Admin API. ## How to take action When a device hash is flagged as suspicious, you can take immediate action to mitigate the risk and protect your end-users. To do this, you can either use: - The [Device hash](https://dashboard.signicat.com/mobileid/risk-indicators/device-hash) risk indicator page in the Signicat Dashboard. - The [Statistics](pathname:///apis/mobileid-admin/#tag/Statistics) resource in the **MobileID Admin API**. To learn about what actions you can take, see the sections below. ### Investigate devices You can retrieve a complete list of all users and devices tied to a specific device hash, so that you can audit their recent authentication activity. ### Lock devices You can lock all active MobileID devices associated with a suspicious device hash using a single operation. Once locked, the device can no longer be used for authentication or signing. ### Block future registrations :::note Coming soon This action is coming soon! ::: You can add a device hash to a blocklist to prevent any new MobileID devices from being created on that specific physical device in the future. ## How to get access The **Device hash** risk indicator is part of an add-on product for MobileID that must be purchased. To get access to this feature, please [contact sales](https://www.signicat.com/contact/contact-sales). :::note Free trial This add-on product comes with a free trial period! ::: Once you have bought the product, there is no action or configuration required by you to start capturing data. This is because the `deviceHash` is an **Always collected** risk attribute in the MobileID SDKs, which means that it is automatically collected by default. --- ## Risk indicators Our risk indicators feature consists of rule-based indicators that analyse data from active users, devices, and various contextual parameters. These are used to flag suspicious events and potentially fraudulent activities. ## How it works Our risk indicators feature is built upon the risk attributes that are collected for each transaction. Based on this non-real-time data, our system uses rule-based models to evaluate the risk attributes and determine if the activity, user or device should be flagged for potential risk. :::note Note For some of the risk indicators, you need to enable the risk attributes before we can give you any indications. ::: ### Available risk attributes For a complete list of the attributes that can be collected, see the [**Risk attributes**](pathname:///apis/reuseid/#section/Common-concepts/Risk-attributes) table in the **Common concepts** section of our ReuseID API reference documentation. ### Configuring risk attributes It is up to you to decide which risk attributes you want to enable for your account. You can update your configuration using the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > [**MobileID**](https://dashboard.signicat.com/mobileid/). 2. In the left menu, go to **Features** > [**Risk data**](https://dashboard.signicat.com/mobileid/features/risk-data). :::note Using REST API instead It is also possible to update your configuration for which risk attributes are collected using our MobileID Admin REST API. To do this, see the [**Update properties of application configuration**](pathname:///apis/mobileid-admin/internal/#tag/Application-configuration/operation/updateAppConfigurationProperties) endpoint. ::: ## How to use risk indicators You can access risk indicators in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > [**MobileID**](https://dashboard.signicat.com/mobileid/). 2. In the left menu, expand the **Risk indicators** dropdown menu, then select a risk indicator. From here, you can: - View any risk indicators that we flag. - Act on the flagged risk indicators. :::tip Example For example, we flag suspicious devices with our **Device hash** risk indicator. From the Signicat Dashboard, you can view the flagged device hash, lock associated users and devices, and block new ones from being added. ::: ### Available risk indicators To learn about the different risk indicators that we offer, make a selection using the buttons below. * [**Device hash**](/docs/mobile-identity/mobileid/features/risk-indicators/device-hash): Get and lock all registrations tied to a device hash using a single operation ### API integration Instead of using the Signicat Dashboard, you can also integrate with our REST API to programmatically get access to and configure the risk indicators. This allows you to automate your risk response workflows, such as automatically locking an end-user's device if a high-risk indicator is triggered, or feed the information into your own risk engine. To learn more, see the **Statistics** resource in the MobileID Admin API reference documentation: * [**MobileID Admin API**](/apis/mobileid-admin/#tag/Statistics): See endpoints for the 'Statistics' resource ## Configure risk indicator rules You can configure the parameters for the different rules that are used to find the risks. This allows you to fine-tune the indicators themselves to fit your specific needs and risk tolerance. :::info What does this mean? For example, you can adjust the threshold for what constitutes a suspicious number of users per device. ::: To see the specific details and configurable parameters for each risk indicator: 1. Go to **Signicat Dashboard** > **Products** > [**MobileID**](https://dashboard.signicat.com/mobileid/). 2. In the left menu, expand the **Risk indicators** dropdown menu, then select a risk indicator. ### API integration You can update the configuration of your risk indicators using our REST API. To learn more, see the **Risk indicators** resource in the MobileID Admin API reference documentation: * [**MobileID Admin API**](/apis/mobileid-admin/#tag/Risk-indicators-configuration): See endpoints for the 'Risk indicators configuration' resource ## How to get access Currently, the risk indicators feature is rolled out in a beta version. During this phase, all customers are automatically granted access to the feature. Once the beta period is completed, this feature will transition into an add-on product that must be purchased. :::note Free trial After the beta period, a free trial period will be offered to let you evaluate the feature before committing. ::: --- ## Signature ## About the MobileID signature API You can use our MobileID signature API as an alternative to our MobileID authentication API. Unlike the authentication operation, the signing operation also returns a signed JSON Web Token (JWT) back to you which contains all relevant transaction data. This allows you to store a third-party proof of the authentication which can be used for non-repudiation. The MobileID signature API also allows you to use a larger data size in the pre-operation context content (`content`). To learn more, see [Operation context maximum character length](pathname:///apis/reuseid/#section/Common-concepts/Operation-context-maximum-character-length) in the ReuseID API reference documentation. ### Which operation should I use? Your requirements for data size and long-term transaction proof will often determine whether you use the MobileID authentication or signing operation. For both APIs: - MobileID retains transaction data for the last 60 days. You can access this data using the MobileID [Get device transactions](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/getDeviceTransactions) endpoint. - Signicat retains transaction data for the last 12 months. You can access this data using the Audit logs service in the Signicat Dashboard. To see this, go to **Signicat Dashboard** > **Settings** > [**Audit logs**](https://dashboard.signicat.com/audit) However, only the MobileID signature API returns a signed JWT that can be stored long-term as proof of the transaction. ## How does the MobileID signature API work? When a signing operation is successfully completed, a signed JWT containing the transaction data is returned in the `signature` field of the response. :::details Click to see example ```json title="Example: Completed signature response" { "type": "SIGNATURE", "accountId": "a-sdge-mokc8nV8siYpbnqxyban", "transactionId": "033e61dc-0585-48ec-a622-194b2fdeebab", "state": "COMPLETED", "created": "2025-01-08T09:55:59.560Z", "completed": "2025-01-08T09:56:02.895Z", "device": { "id": "260eeae5-15b0-4c14-92e8-f85ffe67d91c", "state": "ACTIVE", ... }, "user": { "externalRef": "nilnil-test", "id": "6dcb5ccd-faac-4acc-8dcc-d9a2cbe266d5", ... }, "operationProperties": { "authLevel": "TWO_FACTOR", "authMethod": "DEVICE_PIN", "preOperationContext": { "content": "Sign this", "mimeType": "text/plain" }, "pushSent": false, "location": { "accuracy": "1.3423532645642E13", ... }, "geofencing": { "countryCode": "NO", ... }, "sessionExpiryTime": "2025-01-08T10:00:59.607Z", "clientData": "", "signedJwtCertificateOption": "NONE" }, "riskAttributes": { "isDebuggerConnected": "false", "operatingSystemType": "Android", ... }, "signature" : "eyJ4NXQjUzI1NiI6IjMyNW ... A3dimBkXJza8jLOtC" } ``` ::: A signed JWT consists of three parts: - [Header](#header) - [Payload](#payload) - [Signature](#signature-1) :::info Want to learn more? To learn more about JWTs, see the [RFC documentation](https://www.rfc-editor.org/rfc/rfc7519). ::: ### Header The JWT from the MobileID signature operation can contain the following fields in the header: :::CustomTable | **Field** | **Description** | | :-- | :-- | | `x5t#S256` | A Base64URL-encoded SHA-256 thumbprint (also referred to as the digest) of the DER encoding of the X.509 certificate. This corresponds to the key used to digitally sign the JWS. To learn more about X.509 certificates, see the [RFC documentation](https://www.rfc-editor.org/rfc/rfc5280). | `alg` | The JWT signing algorithm. | ::: ```json title="Example: MobileID signature JWT header" { "x5t#S256": "0456779b6966effdfc2d6d769edd3de25a7c295d27bdcc100efc8cf50f2a5372", "alg": "RS256", } ``` ### Payload The JWT from the MobileID signature operation contains the following claims in the payload: :::CustomTable | **Claims** | **Description** | | :-- | :-- | | `iss` | The issuer claim. This is always Signicat AS. | | `transactionData` | The transaction data claim. This custom claim is a Base64-encoded version of the whole response. | | `sub` | The subject claim. This is the ReuseID user ID (`userId`). | | `iat` | The issued at claim. This is the time when the JWT was issued. | | `jti` | The JWT ID claim. This is a unique identifier for the JWT. | ::: ```json title="Example: MobileID signature JWT payload" { "iss": "Signicat AS", "transactionData": "eyJ0cmFuc2FjdGlvbklkIjoiZWUxMmEyYTktYzIzYS00NjczLWEyZjgtNDU1MzI1OTczZGNiIiwiYWNjb3VudElkIjoiYS1zZGdlLU4yN0dqUFN6WE84SkxjZjhHMUFOIiwic3RhdGUiOiJDT01QTEVURUQiLCJvcGVyYXRpb25Qcm9wZXJ0aWVzIjp7ImF1dGhMZXZlbCI6IlRXT19GQUNUT1IiLCJjb3JyZWxhdGlvbklkIjoiM2VhZTU4MzAtM2VlMi00ZTJjLWEzNGYtMTczYmRhOTg1ZDU5IiwiYXV0aE1ldGhvZCI6IkRFVklDRV9BTkRST0lEX0JJT01FVFJJQ19QUk9NUFQiLCJzZW5kUHVzaCI6ZmFsc2UsInByZU9wZXJhdGlvbkNvbnRleHQiOnsidGl0bGUiOiJDb25zZW50IFNpZ24iLCJjb250ZW50IjoibG9rbyIsIm1pbWVUeXBlIjoidGV4dC9wbGFpbiJ9LCJwdXNoU2VudCI6ZmFsc2UsInNlc3Npb25FeHBpcnlUaW1lIjoiMjAyMi0xMS0xMFQxMzozNDo0MC4wNDBaIiwic2lnbmVkSnd0Q2VydGlmaWNhdGVPcHRpb24iOiJOT05FIn0sInJpc2tBdHRyaWJ1dGVzIjp7fSwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MDkuOTExWiIsImNvbXBsZXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MTYuMDM1WiIsImRldmljZSI6eyJpZCI6ImM3NDNiNTg4LWY1N2UtNGZhYy04OWMyLTZmYWMyMDU4OTc2OCIsIm5hbWUiOiJzYW1wbGVEZXZpY2UiLCJzdGF0ZSI6IkFDVElWRSIsImxhc3RPcGVyYXRpb25UeXBlIjoiU0lHTklORyIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNi4wMDhaIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDk6MDQuMDkyWiJ9LCJ1c2VyIjp7ImV4dGVybmFsUmVmIjoiZGV2NSIsImlkIjoiZTY5N2ExMzEtMGZlMy00MDgyLTljNWItOTk0MTE3MDMyOWQyIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDg6NTQuMjQ4WiIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNS45ODZaIiwic3RhdGUiOiJBQ1RJVkUifX0=", "sub": "e697a131-0fe3-4082-9c5b-9941170329d2", "iat": "1668087196", "jti": "ab993e6b-6788-47cb-803e-38fc5413b8ae", } ``` ### Signature The signature is generated by signing the Base64-encoded header and payload with a private key, based on the algorithm specified in the header. The corresponding public key is used for validation. Your application should always validate the signature of the signed JWT. :::info Want to learn more? For general recommendations on JWT signature validation, see the [RFC documentation](https://www.rfc-editor.org/rfc/rfc7519). ::: #### How to get the public key The public key needed to validate a signature can be obtained by using the [Get signing certificates](pathname:///apis/mobileid-admin/#tag/Signing-certificates/operation/getSigningCertificates) endpoint in the Signicat MobileID Admin API. Here, you can also obtain previous certificates that are deactivated and any available future certificates. :::tip Use the Signicat Dashboard For testing and development use, you can also use the Signicat Dashboard to obtain the public key. To do this: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Details**](https://dashboard.signicat.com/mobileid/details). 2. Select the **Signing certificates** tab. ::: #### Cache the certificate list We recommend that you cache the certificate list locally, then use this cache for signature validation. This means that you do not need to get it for each signature operation. You should refresh the cache with new data from the [Get signing certificates](pathname:///apis/mobileid-admin/#tag/Signing-certificates/operation/getSigningCertificates) endpoint when you see a new `x5t#S256` thumbprint, or when the cache has expired. :::tip Cache expiry In order to pick up on any certificate deactivations, you should set the cache expiry to be reasonably short. ::: ## Key rotation Periodic key rotation is considered good practice, as it ensures a higher level of security. This means that the certificates that you can obtain are subject to change at any given time. When validating a signature, you should consider the following: - If a signature validation fails, check if the thumbprint in the `x5t#S256` matches the sha256Fingerprint of the certificate that you are using. If the thumbprint does not match, then the signing certificate may have been rotated. - If you are validating an older signature, then the signing may have been performed with an old certificate, found in the deactivated certificate list. --- ## How it works(Mobileid) Our MobileID product is comprised of two main components: - ReuseID identity store - Mobile authentication These components are fulfilled by combining a ReuseID identity store for creating reusable identities with our MobileID authentication product using Encap SCA for authentications and authorisations using a mobile device. By securely binding an end-user to a mobile device, the device can then be used to authenticate and authorise end-user operations. ## Integrate with MobileID To integrate with MobileID, there are two aspects that you need to consider: - Backend REST API - Mobile SDK - Android - iOS You can either integrate our SDK into your own mobile app, or you can use our white-label Authenticator App which can be customised to your branding requirements. If you choose to integrate the SDK into your own app, you have complete control over the end-user journey and experience. Diagram showing integration with MobileID ## ReuseID identity store Once your end-user has successfully created a ReuseID user in our identity store, they can add MobileID devices used for authentication and authorisation operations in your mobile app. A ReuseID user can have multiple MobileID devices registered. You also have the flexibility to add any custom attributes to a ReuseID user, such as an address or phone number. Identity attributes are stored within our ReuseID identity store as key-value pairs. The identity of a end-user is proofed outside of ReuseID. ReuseID allows you to support different proofing mechanisms depending on your target markets, whilst still using the same identity store and mobile authentication solution. For the proofing mechanism, you can use: - Any of our [eIDs](/docs/eid-hub/e-ids/). - Any of our [electronic identity verification (eIDV) services](/docs/id-document-and-biometric-verification/#eidv-services). - Any other proofing mechanism that you have already implemented. ### User management operations - Create new users - Get a user and its attributes - Update a user and its attributes - Deactivate a user - Lock and unlock a user :::info Want to learn more? To learn more about these operations, see the [User](pathname:///apis/reuseid/#tag/User) API in our ReuseID API reference documentation. ::: ## Mobile authentication Once a MobileID device has been successfully registered for a ReuseID user, they can then be used for authentication and authorisation operations in your app. The Encap SCA (strong customer authentication) product that MobileID uses is based on a challenge and response protocol. All communication between our MobileID backend and the SDK is secured with [application layer encryption](/docs/mobile-identity/mobileid/features/end-to-end-encryption.mdx). This protects every message passed between the MobileID service and the mobile app using our SDK. :::note Compliance Our solution is compliant with the [Payment Services Directive (PSD2)](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2) and can be used for high-value transactions. ::: ### MobileID device operations With MobileID's device operations, you can conduct a: - [Registration](#registration) - [Authentication and authorisation](#authentication-and-authorisation) - [Consent signature](#consent-signature) #### Registration This operation enables you to register a new MobileID device to an identity. An identity must have at least one registered device in order to perform any of the other device operations. The following sequence diagram shows an example flow to register a new device for an existing ReuseID user from within your mobile app: ```mermaid sequenceDiagram title MobileID registration actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as ReuseID (MobileID) user->>app: End-user opens app app->>sp: Start registration sp->>mobileid: POST /devices/registrations with userId mobileid-->>sp: activationCode sp-->>app: activationCode app->>mobileid: (SDK call) startActivation with activationCode mobileid-->>app: startActivation response note over user, app: End-user adds biometrics or PIN app->>mobileid: (SDK call) finishActivation mobileid-->>app: Activation result mobileid->>sp: POST /callback with registration result sp-->>mobileid: OK ``` :::info Want to learn more? To learn more about this operation, see the [MobileID registration](pathname:///apis/reuseid/#tag/MobileID-Registration) API in our ReuseID API reference documentation. ::: #### Authentication and authorisation This operation enables you to trigger an authentication or an authorisation for a ReuseID user. For all authorisations, we dynamically link the context to the transaction. This ensures compliance with the PSD2 RTS. It can be used whenever: - You need to verify that it is the same user accessing your services. - You need the user to confirm a transaction. - You need the user to perform a payment authorisation. The following sequence diagram shows an example flow to initiate and complete an authentication or authorisation operation from within your mobile app: ```mermaid sequenceDiagram title MobileID authentication actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user opens app app->>sp: Start authentication sp->>mobileid: POST /devices/authentications with userId and deviceId mobileid-->>sp: OK sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication result note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result mobileid->>sp: POST /callback with authentication result sp-->>mobileid: OK ``` :::info Want to learn more? To learn more about this operation, see the [MobileID authentication](pathname:///apis/reuseid/#tag/MobileID-Authentication) API in our ReuseID API reference documentation. ::: #### Consent signature This operation is similar to the authorisation operation, however, we return a signed JWT of the transaction. This JWT can be stored and used to prove that the transaction occurred and was authorised by the user. The following sequence diagram shows an example flow to initiate and complete a signing operation from within your mobile app: ```mermaid sequenceDiagram title MobileID signature actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as MobileID user->>app: End-user opens app app->>sp: Start signature sp->>mobileid: POST /devices/signatures with userId and consent text mobileid-->>sp: OK sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication result note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result mobileid->>sp: POST /callback with signature result sp-->>mobileid: OK ``` :::info Want to learn more? To learn more about this operation, see the [MobileID signature](pathname:///apis/reuseid/#tag/MobileID-Signature) API in our ReuseID API reference documentation. ::: #### Device operation endpoints Each device operation has three endpoints: - Start an operation - Get status of an operation - Cancel an operation #### Device operation steps Each device operation consists of three steps: ##### 1. Initiate the operation To initiate an operation, a request must be made to our REST APIs. You can learn about the different MobileID operations in our [ReuseID API reference documentation](/apis/reuseid/). ##### 2. Carry out the operation on the device Once an operation has been initiated, it is carried out from within your application using our SDK. Most of our SDK APIs consist of a start and a finish operation. You can learn about our SDKs in our [iOS](/docs/mobile-identity/encap/sdk-ios/) and [Android](/docs/mobile-identity/encap/sdk-android/) SDK documentation. ##### 3. Finalise the operation When the operation is completed on the device and our service has verified the operation, we will send a callback notification to your server with the result of the operation. ### Device management operations Device management operations are API calls that allow you to manage all devices in your MobileID identity store. They do not require any device interaction. For example, you can: - Get device information - Deactivate a device - Lock and unlock a device :::info Want to learn more? To learn more about these operations, see the [MobileID device management](pathname:///apis/reuseid/#tag/MobileID-device-management) API in our ReuseID API reference documentation. ::: --- ## MobileID Signicat MobileID lets you authenticate and authorise end-user operations securely with your mobile app. It offers a rich feature set, strong security and a seamless user experience. By keeping the entire user journey inside your app, you can offer familiarity to you end-users, build long-term trust and increase conversions. You can either integrate our SDK into your own mobile app, or you can use our white-label Authenticator App which can be customised to your branding requirements. ## About MobileID - It creates a strong and immutable binding between a ReuseID user and one or more MobileID devices. - It allows you to achieve two-factor authentication by combining on-device biometrics or a PIN with the device itself. - It supports omni-channel transactions, meaning the transaction is always approved by your customer in your mobile app, regardless of what channel the transaction was initiated in. - It offers many additional features such as account recovery, app attestation, geofencing and signing. - It is fully PSD2-compliant and supports Strong Customer Authentication (SCA), making it suitable for financial services, regulated industries and high-trust use cases. - It does not require any redirects or additional downloads, as it works directly in your mobile app. - It works the same way across all countries, making it ideal for businesses operating in multiple markets. ### Compliance MobileID is compliant with both: - [Payment Services Directive (PSD2)](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2) - [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/) ### Digital identity lifecycle A digital identity has a lifecycle which consists of four stages. MobileID has a role in each of these stages, simplifying the process of building your own digital identity: :::CustomTable{tableName="Stages in the lifecycle of a digital identity" columnWidths="10% 40% 50%"} | **Stage** | **Description** | **Using MobileID** | | :-- | :-- | :-- | | Sign up | Sign up new customers, verify identities and attributes, create credentials for returning use. | Your end-users can create a ReuseID user and add at least one device, to be used for all future **sign-in** and **sign-it** transactions. **Note**: We ensure that the end-user performing the transaction is the same as the one who signed up. | | Sign in | Sign in customers to any services. | Your end-users can authenticate and authorise operations using biometrics or PIN in your mobile app, across all channels and countries. | | Sign it | Provide consent and authorise transactions. | Your end-users can sign to authorise payments and consent transactions, ensuring that you stay compliant and secure. | | Sign off | Sign off a customer when they want to stop using the services and remove their identity. | You can remove identity attributes and credentials from MobileID if an end-user wants to stop being a customer or using your services. | ::: ## Get started * [**Try it out**](/docs/mobile-identity/mobileid/quick-start-guides/try-it-out): Learn how to do a MobileID authentication using the Signicat Dashboard * [**Quick start guide**](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication): Learn how to do a MobileID authentication using the ReuseID API * [**Use cases**](/docs/mobile-identity/mobileid/use-cases/): Get inspired by how you can use MobileID in different use cases * [**How it works**](/docs/mobile-identity/mobileid/how-it-works): Learn about how MobileID works * [**Features**](/docs/mobile-identity/mobileid/features/): Learn about MobileID features in our feature guides * [**API reference**](/docs/mobile-identity/mobileid/api-reference/): Explore endpoints and properties with example requests and responses ## Releases and upgrades * [**Release notes**](/docs/mobile-identity/mobileid/release-notes): View MobileID release notes * [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide): View MobileID version information and our upgrade guide ## Support * [**Error codes**](/docs/mobile-identity/mobileid/error-codes): View the error codes for MobileID * [**Best practices**](/docs/mobile-identity/mobileid/best-practices): Learn about best practices when implementing MobileID --- ## Mobile SDKs If you want to integrate with MobileID using your own app instead of our white-label Authenticator App, then you can use our mobile SDKs for Android and iOS devices. To learn about our SDKs, how to integrate them and how to understand error codes, see our documentation using the buttons below. :::note Note Be aware that the SDK documentation is currently held in the Encap SCA product space. The content outside of the SDK documentation in the Encap SCA product space is not relevant to you. Please ensure that you navigate back to the MobileID documentation for anything unrelated to the mobile SDKs. ::: * [**Android SDK**](/docs/mobile-identity/encap/sdk-android): Use our SDK to perform authentication and authorisation operations in your mobile app * [**iOS SDK**](/docs/mobile-identity/encap/sdk-ios): Use our SDK to perform authentication and authorisation operations in your mobile app * [**SDK error codes**](/docs/mobile-identity/encap/sdk-error-codes): View the error codes for our mobile SDKs --- ## Quick start guides(Quick-start-guides) Our quick start guides show you how to test out MobileID authentication and more with API requests and a tool of your choice. :::info Want to try without coding? If you want to try out basic MobileID operations using our no-code interface in the Signicat Dashboard, then see the [Try it out](/docs/mobile-identity/mobileid/quick-start-guides/try-it-out) page. ::: * [**Authentication using MobileID**](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication): Learn how to do a MobileID authentication using the ReuseID API --- ## Quick start guide(4) # Quick start guide Learn how to test out ReuseID with MobileID authentication using the Authenticator App and the ReuseID API. This quick start guide shows you how to: 1. Get set up for testing MobileID authentication with the Authenticator App. 2. Create a ReuseID user. 3. Register a MobileID device 4. Perform a MobileID authentication. :::info Want to try MobileID without making API requests? This guide requires that you make API requests using a tool of your choice. If you want to try out MobileID without making API requests, then you can use the [Try it out](https://dashboard.signicat.com/mobileid/quick-start-guides/try-it-out) page in the Signicat Dashboard. Here, you can use a button to trigger MobileID operations instead. ::: ## Prerequisites ### 1. Connect to the ReuseID API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note Add permissions for ReuseID When you have created an API client, make sure to add permissions for **ReuseID MobileID Device API** ::: ### 2. Onboard to MobileID You need to onboard your account to MobileID. To do this: 1. Go to **Signicat Dashboard** > **Products** > [**MobileID**](https://dashboard.signicat.com/mobileid/). 2. Click the **+ Add MobileID** button. ## Set it up Next, you have to set up a tool for triggering operations and access our Authenticator App to perform them. ### 1. Set up ReuseID in Postman :::note Using other tools This guide provides steps for using [Postman](https://www.postman.com/downloads) as a tool for initiating the APIs, however, you can use the preferred tool of your choice. ::: To set up ReuseID in Postman and obtain an access token: 1. Open Postman. 2. Import the collection. To do this: 1. Navigate to the **Collections** tab on the left-hand side of the screen, then click the **Import** button. Screenshot showing import of the collection into Postman 2. In the blank field in the dialogue box, paste the URL to our ReuseID API specification `https://api.signicat.com/reuseid/core/openapi.json`. :::tip Our recommendation We recommend that you generate the request and response parameters from the examples in the schema, and that you create folders according to the tags. To do this: 1. Click the **View import settings** button. 2. In the **Parameter generation** section, select **Example** from the dropdown menu. 3. In the **Folder organization** section, select **Tags** from the dropdown menu. ::: 3. Click the **Import** button in the dialogue box to finalise the import. 3. Create variables. To do this, click the **Variables** tab, and add the following: :::CustomTable{columnWidths="25% 75%"} | Variable | Value | | :-- | :-- | | `baseUrl` | This variable becomes present after import.

Make sure that the value is `https://api.signicat.com/reuseid/core`. | | `authClientID` | The client ID that you obtained when you created the API client. | | `authClientSecret` | The client secret that you obtained when you created the API client. | ::: Screenshot showing creation of variables in Postman 4. Set up authorisation. To do this, go to the **Authorization** tab and update the following: :::CustomTable{columnWidths="25% 75%"} | Name | Value | | :-- | :-- | | Type | `OAuth 2.0` | | Grant type | `Client Credentials` | | Access Token URL | `https://api.signicat.com/auth/open/connect/token` | | Client ID | `{{authClientID}}` | | Client Secret | `{{authClientSecret}}` | | Scope | `signicat-api` | ::: Screenshot showing set up of authorisation in Postman 5. Click on the **Get new access token** button to get an access token. 6. To add the token to the requests, click **Proceed**, then **Use Token**. 7. Save your changes. :::tip Auto-refresh your access token To automatically refresh your access token after it has expired, enable the **Auto-refresh token** toggle button under the **Authorization** tab. You can only enable auto-refresh tokens after you have received your first valid token. ::: :::note Success! You have now set up Postman for the ReuseID API. ::: ### 2. Install our Authenticator App To perform the operations on a mobile device you can use our [Authenticator App](/docs/mobile-identity/mobileid/authenticator-app/). The Authenticator App is our white-label mobile application which enables you to perform operations on a mobile device, so that you can start testing out MobileID as quickly as possible. :::details Want to use our SDK instead? It is also possible to use our SDK and integrate it into your own app instead. To get access to the SDK, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. When using the SDK, you need to configure the controller to use your MobileID account. To do this, you use the same values as those required to configure the Authenticator App: - See the [configure our Authenticator app](#3-configure-our-authenticator-app) section for the values to configure. - See our [Android](/docs/mobile-identity/encap/sdk-android/getting-started.mdx#configure-the-controller) and [iOS](/docs/mobile-identity/encap/sdk-ios/getting-started.mdx#configure-the-controller) SDK documentation for details on how to configure the controller. ::: #### iOS To install our Authenticator App on your iPhone, you have to: 1. Scan the QR code below on your mobile device: QR code to install the iOS Authenticator App 2. Install the latest version. #### Android To install our Authenticator App on your Android, you have to: 1. Scan the QR code below on your mobile device: QR code to install the Android Authenticator App 2. Install the latest version. ### 3. Configure our Authenticator App Once you have installed the Authenticator App, you need to configure it to use your MobileID account. To do this, you need to update the following values: - Application ID (`applicationId`) - Public E2E key (`publicKey`) - Server URL (`https://api.signicat.com/encore/encap`) :::note Note Our server URL is the same for both sandbox and production accounts. ::: #### How to obtain these values To get your application ID (`applicationId`) and public E2E key (`publicKey`), you need to: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Details**](https://dashboard.signicat.com/mobileid/details). 2. Click on **Quick configuration** in the top-right corner. :::note Manually add values If you do not wish to use the QR code scanner, then you can also find the **Application ID** value under the **Account tab**, and the **Public key** value under the **E2E keys** tab. ::: #### How to set these values :::note Other options It is also possible to select a configuration from the dropdown list, or manually add your own configuration by clicking `+`. ::: ## Try ReuseID with MobileID authentication You have now completed all required preparations and are ready to perform MobileID operations. ### 1. Create a ReuseID user To create a ReuseID user: 1. In Postman, navigate to **Signicat ReuseID API reference** > **User** > **Create user**. 2. Under the **Body** tab, you can input your own request body. ```json title="Example: Request to create a ReuseID user" { "attributes": { "first_name": "Jane", "last_name": "Smith" } } ``` 3. Click the **Send** button. ```json title="Example: Response from creating a ReuseID user" { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "state": "ACTIVE", "attributes": { "last_name": "Smith", "first_name": "Jane" } } ``` :::note Success! You have now created a ReuseID user. ::: :::tip Our recommendation We recommend that you save the `id` of your ReuseID user (user ID), as it is needed in future operations. ::: ### 2. Register a MobileID device Now that you have created a ReuseID user, you can register a MobileID device. To do this: 1. In Postman, navigate to **Signicat ReuseID API reference** > **MobileID registration** > **Start registration**. 2. Under the **Body** tab, you can input your own request body. For this API, it is required to set the user ID (`userId`). This is the ID of the ReuseID user that you created in the previous section. ```json title="Example: Request to register a MobileID device" { "userId": "76bfe9e6-1fe2-4b92-b742-a66015a98981" } ``` 3. Click the **Send** button. 4. You have now started a registration operation. The response contains an `activationCode`, which you need in the next step. :::details Show activation code as QR code in Postman To get the best the user experience, Postman can show the activation code as a QR code. This means that you do not have to manually type the code in the Authenticator App. To do this, add the following snippet to **Script** > **Post-response** in the `POST` request: ``` let response = pm.response.json(); let qrcTemplate = ''; pm.visualizer.set(qrcTemplate, {}); ``` ::: ```json title="Example: Response from registering a MobileID device" { "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO", "transactionId": "c9a0d33d-3366-4561-b47f-ec48428e2962", "state": "PENDING", "created": "2023-08-16T11:33:08.537Z", "device": {}, "user": { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "state": "ACTIVE" }, "operationProperties": { "activationCode": "057771", "registrationMode": "REGISTRATION", "sessionExpiryTime": "2023-08-16T11:34:38.441Z" } } ``` 5. Open the Authenticator App. 6. Click on the button to start the registration operation on the device. 7. Scan or enter the `activationCode` that was obtained in **Step 4**. :::note Note The activation code is only valid until the session expiry time (`sessionExpiryTime`). ::: 8. Select a PIN. 9. Select if you want to activate biometrics. 10. In Postman, navigate to **MobileID registration** > **Get state of ongoing registration**. 11. Under the **Params** tab, update the value of `transactionId` to the value you obtained in the **Start registration** response. 12. Click the **Send** button. ```json title="Example: Response from fetching the state of a MobileID registration" { "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO", "transactionId": "c9a0d33d-3366-4561-b47f-ec48428e2962", "state": "COMPLETED", "created": "2023-08-16T11:36:57.759Z", "completed": "2023-08-16T11:37:19.110Z", "device": { "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61", "state": "ACTIVE", "lastOperationType": "REGISTRATION", "lastUsed": "2023-08-16T11:37:19.122Z", "created": "2023-08-16T11:37:19.111Z" }, "user": { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "lastUsed": "2023-08-16T11:37:19.100Z", "state": "ACTIVE" }, "operationProperties": { "activationCode": "662815", "authLevel": "TWO_FACTOR", "registrationMode": "REGISTRATION", "sessionExpiryTime": "2023-08-16T11:38:27.660Z" } } ``` :::note Success! You have now registered and activated a MobileID device. ::: :::tip Our recommendation We recommend that you save the `id` of your MobileID device (device ID), as it is needed in future operations. ::: ### 3. Authenticate with MobileID Now that you have registered a MobileID device, you can authenticate with that device. To do this: 1. In Postman, navigate to **Signicat ReuseID API reference** > **MobileID authentication** > **Start authentication**. 2. Under the **Body** tab, you can input your own request body. For this API, it is required to set both the user ID (`userId`) and the device ID (`deviceId`). These are the IDs of the ReuseID user and MobileID device that you obtained in the previous sections. ```json title="Example: Request to authenticate" { "userId": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "device": { "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61" }, "operationProperties": { "preOperationContext": { "content": "Approve your first MobileID authentication", "mimeType": "text/plain" }, "postOperationContext": { "content": "Cool! You have successfully completed a MobileID authentication", "mimeType": "text/plain" } } } ``` 3. Click the **Send** button. ```json title="Example: Response from the authentication" { "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO", "transactionId": "e33c5cd4-03d2-42ca-acc1-407a72c234ce", "state": "PENDING", "created": "2023-08-16T11:53:24.863Z", "device": { "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61", "state": "ACTIVE", "lastOperationType": "AUTHENTICATION", "lastUsed": "2023-08-16T11:51:14.703Z", "created": "2023-08-16T11:37:19.111Z" }, "user": { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "lastUsed": "2023-08-16T11:51:14.693Z", "state": "ACTIVE" }, "operationProperties": { "postOperationContext": { "content": "Cool! You have successfully completed a MobileID authentication", "mimeType": "text/plain" }, "preOperationContext": { "content": "Approve your first MobileID authentication", "mimeType": "text/plain" }, "pushSent": true, "sessionExpiryTime": "2023-08-16T11:54:54.955Z" } } ``` 4. Open the Authenticator App. 5. The app shows a dialogue box with the pre-operation context (`preOperationContext`). If you do not see the pre-operation context, then you can use the reload button. 6. Click the **Approve** button. 7. In Postman, navigate to **MobileID authentication** > **Get state of ongoing authentication**. 8. Under the **Params** tab, update the value of `transactionId` to the value you obtained in the **Start authentication** response. 9. Click the **Send** button. ```json title="Example: Response from fetching the state of an authentication" { "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO", "transactionId": "e33c5cd4-03d2-42ca-acc1-407a72c234ce", "state": "COMPLETED", "created": "2023-08-16T11:53:24.863Z", "completed": "2023-08-16T11:53:37.407Z", "device": { "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61", "state": "ACTIVE", "lastOperationType": "AUTHENTICATION", "lastUsed": "2023-08-16T11:53:37.392Z", "created": "2023-08-16T11:37:19.111Z" }, "user": { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "lastUsed": "2023-08-16T11:53:37.382Z", "state": "ACTIVE" }, "operationProperties": { "postOperationContext": { "content": "Cool! You have successfully completed a MobileID authentication", "mimeType": "text/plain" }, "authLevel": "TWO_FACTOR", "authMethod": "DEVICE_IOS_FACE_ID", "preOperationContext": { "content": "Approve your first MobileID authentication", "mimeType": "text/plain" }, "pushSent": true, "sessionExpiryTime": "2023-08-16T11:54:54.955Z" } } ``` :::note Success! You have now completed a MobileID authentication. ::: :::info Want to learn more? You can find information about all of the different authentication endpoints in our [ReuseID API reference](pathname:///apis/reuseid/#tag/MobileID-Authentication) documentation. ::: ## Learn more You can explore our developer documentation to learn more about what you can do with MobileID and further test out the product. * [**Use cases**](/docs/mobile-identity/mobileid/use-cases/#examples): Get inspired by how you can use MobileID in different use cases * [**How it works**](/docs/mobile-identity/mobileid/how-it-works): Learn about the operations that make up the integration process * [**Features**](/docs/mobile-identity/mobileid/features/): Learn about MobileID features in our feature guides * [**API reference**](/docs/mobile-identity/mobileid/api-reference/): Explore endpoints and properties with example requests and responses --- ## Try it out(Quick-start-guides) The **Try it out** page in the Signicat Dashboard is the quickest way for you to test out MobileID. All you need is: - An account in the Signicat Dashboard - A mobile device Use the simple interface to perform MobileID registrations and authentications with the click of a button. No coding is required. To test it yourself, see the [Try it out](https://dashboard.signicat.com/mobileid/try-it-out) page and follow the on-screen instructions. ## Tutorial video This video shows you how to use the MobileID **Try it out** page in the Signicat Dashboard. ## How to start over You can try out the registration process as many times as you like. To start over, you need to deactivate the existing account on the device. To do this, open the menu in the Authenticator App, then press the **Deactivate** button. Once deactivated, you can begin a new onboarding. --- ## Authenticator App(Release-notes) :::info Follow the release notes on this page for the latest updates. ::: ### Release 5.2 #### Scrolling context on operations We have implemented scroll functionality for long-form text within the operation's context. This means that you can utilise longer pre-operation and post-operation context messages to display in your authentication operations. :::info What is Operation Context? To learn more, see our [Operation Context](/docs/mobile-identity/mobileid/features/operation-context/) feature documentation. ::: #### Support for ReuseID onboarding with ReadID When onboarding with ReuseID, the app now supports NFC scanning with ReadID for onboarding and step-up flows. :::info What is ReuseID onboarding? To learn more, see our [ReuseID onboarding](/docs/reuseid/identity-proofing/ready-made/onboarding/) documentation. ::: #### Changes in App ID Capabilities (iOS only) From version 5.2, we need the **Access Wi-Fi Information** capability to be enabled under App ID. To do this, you need to go to Apple Developer Portal and edit your existing App ID. This change makes your provisioning profile unsupported. You need to renew it once your App ID is updated by going to **Provisioning Profile** and editing it. :::warning Important You need to send the new version of the provisioning profile to us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: #### Updated target SDK to Android 16 We upgraded the target SDK to Android 16. This ensures compatibility, security, and performance with the latest Android operating system. #### Improvements and bug fixes We have made general improvements and bug fixes, enhancing the app's overall stability and maintainability. #### Encap SCA SDK upgrade We have upgraded the app to the latest version of the Encap SCA SDK, **3.21**. This release gives you access to the newest set of risk attributes. To learn more about the new attributes and how to enable them, see the [MobileID service release notes](/docs/mobile-identity/mobileid/release-notes/service/#new-risk-data-attributes). ### Release 5.1 #### Flow improvements and bug fixes We have made general improvements to our Authenticator App, refined the user experience across different devices and enhanced the app's overall stability and maintainability. #### Minimum iOS version increased to 16 In order to support the newer features provided by Apple, we have increased the minimum iOS version required to run our Authenticator App from **15** to **16**. :::note What is the impact? The now unsupported iOS 15 is several generations old, so its individual usage percentage is extremely small. To learn more, see [App Store Developer Support](https://developer.apple.com/support/app-store/). ::: ### Release 5.0 #### Support for face Authentication We have extended our Authenticator App to support face authentication, a new authentication method based on server-side biometrics. :::info What is Face Authentication? To learn more, see our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/) feature documentation. ::: ##### 1. Configure face authentication To configure our server-side face authentication feature, you need to enable it as an allowed authentication method: 1. Go to **Signicat Dashboard** > **Products** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour), then select the **Authentication** tab. 2. Use the check boxes to enable server-side face as an authentication method, then click **Save**. ##### 2. Use face authentication To use face authentication, the end-user must: 1. Update the Authenticator App to version 5.0. 2. Enable face authentication in the Authenticator App settings, then enroll their face securely. Once enabled, face authentication can be used for authentications. To do this: 1. Initiate an authentication request by setting `DEVICE_SERVER_SIDE_FACE` as the `authMethod`. :::info Try it out You can also [Try it out](https://dashboard.signicat.com/mobileid/try-it-out) in the Signicat Dashboard. To do this, tick the **Use face authentication** box when initiating an authentication ::: 2. When prompted, the end-user performs a facial scan to authenticate securely. ### Release 4.1 #### Support for app configuration using QR codes We have extended our Authenticator App to support scanning of QR codes for configuration. :::note What does this mean? Instead of manually entering information into the fields required for configuring the Authenticator App, you can now scan a QR code to configure it automatically instead. ::: ##### How to scan a QR code 1. Update the Authenticator App to latest version (**4.1**). 2. In the app, tap the gear icon, then tap the QR code scanner icon. 3. Use the UI to correctly position your phone's camera and scan the QR code. The configuration fields are now automatically populated for you. ##### Payload of a QR code In the payload of a QR code, there are four mandatory fields and two optional fields which you can configure. ::::details See all configurable fields **Mandatory fields** :::CustomTable | **Field name** | **Description** | | :-- | :-- | | `name` | The name of the configuration. | | `serverUrl` | The URL of the endpoint. | | `applicationId` | The application ID. To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. | | `publicKey` | The E2E public key. To find this, see [**Details**](https://dashboard.signicat.com/mobileid/details/) for your MobileID account in the Signicat Dashboard. | ::: **Optional fields** :::CustomTable | **Field name** | **Description** | | :-- | :-- | | `timeout` | The amount of time in milliseconds that a network connection waits for until it times out. | | `publicKeyHashes` | The public key hash strings of the HTTPS public keys that are accepted on the communication towards the Encap server. | ::: :::: ### Release 4.0 #### Support for onboarding with ID Document and Biometric Verification We have extended our Authenticator App to support the new onboarding and step-up flows from ReuseID. :::info What is ReuseID? Signicat have launched a new solution called ReuseID. This solution allows you to onboard to MobileID with a VideoID process. You can also trigger the VideoID process as a step-up on existing MobileID end-users. To learn more, see our [ReuseID developer documentation](/docs/reuseid/). ::: #### Configurations for test version of Authenticator App In the test version of our Authenticator App, we have introduced preset configurations for our test and demo environment. ##### Use a preset configuration 1. In the app, tap the gear icon. 2. Click the **Server Config** field to expand the dropdown menu, then select a configuration. The configuration fields are now automatically populated for you. ##### Use your MobileID account It is still possible to configure the Authenticator App to use your own MobileID account. To do this: 1. In the app, tap the gear icon, then tap the plus icon. 2. Enter your MobileID account information in the provided fields. --- ## Release notes(Release-notes) To view the release notes, make a selection using the buttons below: * [**MobileID service**](/docs/mobile-identity/mobileid/release-notes/service): View the release notes for the MobileID service * [**Mobile SDKs**](/docs/mobile-identity/mobileid/release-notes/mobile-sdks): View the release notes for our Android and iOS SDKs * [**Authenticator App**](/docs/mobile-identity/mobileid/release-notes/authenticator-app): View the release notes for our Authenticator App --- ## Mobile SDKs(Release-notes) :::info Follow the release notes on this page for the latest updates. ::: ## 2026 ### 07.07.2026 #### Release: SDK 3.22 :::info Platform: Android, iOS ::: :::warning Important Currently, only Encap SCA customers can upgrade to version 3.22 of our SDK. MobileID customers will be able to upgrade soon; we will keep you informed when this is possible. ::: ##### Overview ###### 3.22 We have released version 3.22 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.22**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-322)   [**iOS SDK 3.22**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-322) :::danger Breaking change for iOS iOS SDK 3.22 introduces breaking changes to support PSD2 compliance and more secure credential handling. In particular, sensitive credential parameters now require `NSMutableString` instead of `String`. To learn more, see the [iOS SDK 3.22 release notes](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-322) and [Security best practices](/docs/mobile-identity/encap/sdk-ios/appendix/security-best-practices.mdx). ::: ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 15.04.2026 #### Patch: Improved performance and ANR prevention for biometric operations :::info Platform: Android ::: ##### Overview ###### 3.20.12 This patch enhances the stability and performance of biometric operations on Android. To prevent potential Application Not Responding (ANR) errors, heavy cryptographic tasks are now processed on a background thread. This change ensures that client applications can now safely initiate biometric operations from either the **Main thread** or an **I/O thread** without risking UI freezes or `StrictMode` violations. For integrations using the `androidx.biometric` library, the SDK is now lifecycle-aware. This ensures that the biometric prompt is automatically and safely cancelled in response to application lifecycle changes. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.20.10** and earlier | **3.20.12** | ### 12.03.2026 #### Patch: Fixed start after deactivate and BiometricPrompt callback issues :::info Platform: Android ::: ##### Overview ###### 3.21.7, 3.20.10 - Fixed an issue where `AsyncCallback` for `finishAuthentication` sends the result more than once for AndroidX BiometricPrompt. - Fixed the race conditions in the BiometricPrompt cancellation logic. - Fixed a crashing issue that would happen when running any start operation quickly after calling `deactivate()`. :::danger Breaking change If you are using state `EncapController.State.PROCESSING_DEACTIVATION`, then this update introduces a breaking change and you need to replace all occurrences with the following in your code: `EncapController.State.PROCESSING_START_DEACTIVATION` `EncapController.State.PROCESSING_FINISH_DEACTIVATION` To learn more, see the [Deactivation states](/docs/mobile-identity/encap/sdk-android/appendix/controller-state/#deactivation-states) section in our **Controller states** documentation. ::: ###### 3.21.7 - Fixed an issue where `isActivated(DEVICE_ANDROID_BIOMETRIC_PROMPT)` was true after removing all fingers. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.6** and earlier | **3.21.7** | | **3.20.9** and earlier | **3.20.10** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 20.02.2026 #### Patch: Fixed operation in progress error for AndroidX BiometricPrompt authentications :::info Platform: Android ::: ##### Overview ###### 3.20.9, 3.21.6 Fixed an issue where the API could return `clientErrorOperationInProgress` for an AndroidX BiometricPrompt authentication, where the BiometricPrompt dialog had become dismissed due to app switching. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.5** and earlier | **3.21.6** | | **3.20.8** and earlier | **3.20.9** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 19.01.2026 #### Patch: Fixed operations failing on Android 11 and below :::info Platform: Android ::: ##### Overview ###### 3.21.5 Fixed an issue that caused SDK operations to fail on devices running Android 11 (API 30) and below, with the error `WifiService: Neither user … nor current process has android.permission.ACCESS_WIFI_STATE`. This error was present on apps lacking the permission required for collecting [Wi-Fi information (SSID and BSSID)](/docs/mobile-identity/encap/sdk-android/configure-features/risk-parameters/#wi-fi-information-ssid-and-bssid), even if these risk parameters were disabled in the server configuration. :::warning Important Previous Android SDK 3.21 releases were removed from our Nexus partner repository. ::: ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.4** and earlier | **3.21.5** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 14.01.2026 #### Patch: Prevent SDK location update requests :::info Platform: Android ::: ##### Overview ###### 3.19.11, 3.20.8, 3.21.4 Introduced `locationEnabled` flag in `EncapConfig`. If you set this flag to `false`, then you prevent the SDK from requesting location updates. To learn more, see our [Location](/docs/mobile-identity/encap/sdk-android/configure-features/location.mdx) feature documentation. ##### Affected versions If your app both: - Requests location permission. - Has location, geofencing, and SSID/BSSID features disabled. Then you can upgrade it to use the latest, patched version and set the `locationEnabled` flag to `false`: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.2** and earlier | **3.21.4** | | **3.20.6** and earlier | **3.20.8** | | **3.19.9** and earlier | **3.19.11** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ## 2025 ### 08.12.2025 #### Patch: Swift Protobuf linking fix :::info Platform: iOS ::: ##### Overview ###### 3.21.2 Fixed an issue that caused duplicate symbol errors during linking when Swift Protobuf was included as a dependency. ##### Affected versions If your app both: - Has Swift Protobuf as dependency. - Uses an affected version of the SDK. Then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.1** | **3.21.2** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 19.11.2025 #### Patch: Location improvements :::info Platform: Android ::: ##### Overview ###### 3.21.3 Fixed an issue where the location was being sent in Encap SDK operations, even if the location was disabled in the device's system settings. ##### Affected versions If your app has either location or geofencing features enabled, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.21.2** and earlier | **3.21.3** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 31.10.2025 #### Release: SDK 3.21 :::info Platform: Android, iOS ::: ##### Overview ###### 3.21 We have released version 3.21 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.21**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-321)   [**iOS SDK 3.21**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-321) ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 30.10.2025 #### Patch: Location permission prompt not triggered in startActivation :::info Platform: iOS ::: ##### Overview ###### 3.20.4 Fixed an issue where the `finishActivation` operation or the `startAuthentication` operation terminated the app due to an uncaught exception. ##### Affected versions If your app both: - Has either location, geofencing or app attestation features enabled. - Uses an affected version of the SDK. Then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.20.2 and 3.20.3** | **3.20.4** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 10.10.2025 #### Patch: Location permission prompt not triggered in startActivation :::info Platform: iOS ::: ##### Overview ###### 3.20.3 Fixed an issue where the `startActivation` operation does not trigger the location permission prompt. This patch also resolves a related bug that could cause subsequent operations to hang when location is disabled and enabled again. ##### Affected versions If your app both: - Has the location or geofencing feature enabled. - Uses an affected version of the SDK. Then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.20.2** | **3.20.3** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 06.10.2025 #### Patch: Fixed clientErrorDowngradeDetected unexpected behaviour issue :::info Platform: Android ::: ##### Overview ###### 3.19.9, 3.20.6 Fixed an issue where `clientErrorDowngradeDetected` is not working as expected, possibly giving false positives. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.20.5** and earlier | **3.20.6** | | **3.19.7** and earlier | **3.19.9** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 03.07.2025 #### Patch: Fixed BiometricPrompt cancellation issue when using wrong fingerprint :::info Platform: Android ::: ##### Overview ###### 3.18.22 Removed a workaround for older OnePlus devices that was causing issues for newer ones. This fixes an issue where using the wrong fingerprint on a modern OnePlus device would sometimes result in BiometricPrompt dismissing itself. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.18.21** and earlier | **3.18.22** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 11.06.2025 #### Patch: Android 16, Biometric Prompt and performance updates :::info Platform: Android ::: ##### Overview ###### 3.20.5 - Adds support for Android 16 (`targetSdkVersion 36`). - This avoids potential build warnings for apps targeting Android 16. - Improves performance. - SDK calls are now faster, with `startAuthentication()` calls now up to 2.5 times faster. - The `AndroidLoggingController` class that provides logging of API calls for development purposes now includes the logging time used by the call. - Removes BiometricPrompt workaround for previous OnePlus phone bug. - This avoids a problem that could occur with wrong biometrics on newer or updated OnePlus phones, that would cause biometric authentication to abort with `clientErrorAndroidBiometricPromptAuthenticationFailed` instead of letting the user retry. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.20.4** and earlier | **3.20.5** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 22.04.2025 #### Release: SDK 3.20 :::info Platform: Android, iOS ::: ##### Overview ###### 3.20 We have released version 3.20 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.20**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-320)   [**iOS SDK 3.20**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-320) ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ##### Upcoming changes In the next SDK version (3.21), we will make the following changes: - For Android, `RecoveryMethod.CLOUD_BACKUP` will be renamed to `RecoveryMethod.CLOUD_BACKUP_RECOVERY_CODE`. - For iOS, the `RecoveryMethod.backup` case will be renamed to `RecoveryMethod.backupRecoveryCode`. - For iOS the SDK minimum supported iOS version will be 15. ### 03.04.2025 #### Patch: Error after storage upgrade :::info Platform: Android ::: ##### Overview ###### 3.18.21, 3.19.7 - This patch sets the right storage name for the storage version during a storage upgrade. - This means that in the rare occasion that a storage upgrade fails to read a specific file, we will not overwrite `clientSaltKeyNextId` the next time we try to upgrade, which causes the `missingParameter` error. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Condition** | **Patched version** | | :-- | :-- | :-- | | **3.15** and earlier | If upgrading to **3.18** or **3.19** | **3.18.21 and 3.19.7** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ## 2024 ### 17.12.2024 #### Patch: Android 15, JSON and BiometricPrompt :::info Platform: Android ::: ##### Overview ###### 3.19.6, 3.18.20 - Adds support for Android 15 (`targetSdkVersion 35`). - This avoids potential build warnings for apps targeting Android 15. ###### 3.19.6, 3.18.20, 3.17.13 - Changes the `JSONObject` type of `clientSaltNextKeyId` to `Long`. - This avoids potential errors in apps with a strict JSON parser, such as `JSONObject["clientSaltNextKeyId"] is not a string`. ###### 3.19.6 - Filters out `DEVICE_BIOMETRIC_PROMPT` on Android 9, when the app does not include AndroidX BiometricPromptEncap. - This ensures that the Encap API supports BiometricPrompt in all apps. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.19.4** and earlier | **3.19.6** | | **3.18.19** and earlier | **3.18.20** | | **3.17.12** and earlier | **3.17.13** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 07.11.2024 #### Patch: Extension support :::info Platform: iOS ::: ##### Overview ###### 3.16.5, 3.17.4, 3.18.4, 3.19.2 - Fixed bug in the migration code for the extension support feature, when multiple Keychain groups are configured. - This bug results in a missing `deviceHash` after migrating to extension support. It causes the SDK to generate a new value on the next authentication attempt, which results in a `deviceHash` mismatch. It is then not possible to authenticate with that registration. #### Affected versions If your app both: - Uses the extension support feature, in combination with multiple Keychain groups configured for the app. - Uses an affected version of the SDK. Then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.16** | **3.16.5** | | **3.17** | **3.17.4** | | **3.18** | **3.18.4** | | **3.19** | **3.19.2** | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 08.08.2024 #### Release: SDK 3.19 :::info Platform: Android, iOS ::: ##### Overview ###### 3.19 We have released version 3.19 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.19**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-319)   [**iOS SDK 3.19**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-319) ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ##### Upcoming changes In the next SDK version (3.20), we will make the following changes: - Bump the minimum supported platform versions to Android 9.0 (API 28). ### 22.05.2024 #### Patch: Crash in native code :::info Platform: Android ::: ##### Overview ###### 3.14.8, 3.15.6, 3.16.8, 3.17.12, 3.18.19 Added fix in the native code to support no Java package name in the Activity or Application. - This avoids affected Encap SDKs having a crash in the native code `libencap-android-api.so` upon startup of the app, following obfuscation with version 8 or higher of the Android Gradle Plugin. For example: ``` signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x0 Cause: null pointer dereference x0 0000000000000000 x1 000000000000002e x2 00000000000003fe x3 0000007fc4ac5408 x4 0000000000000003 x5 0000000000000004 x6 0000000000008048 x7 24ff3a6d6e687360 x8 0000000000000000 x9 0000000000000000 x10 0000007315aa8000 x11 0000000000000020 x12 0000000000000009 x13 00000000d047da0c x14 0000000000000069 x15 000000000000006f x16 00000072d93d83c8 x17 00000075a03c5244 x18 00000075b3f4a000 x19 b4000073b5aa6f50 x20 00000075b4c8e08d x21 b400007315ab56f0 x22 00000075b39ae000 x23 b400007345ad04e0 x24 0000007fc4ac6638 x25 00000072d93d6374 x26 b400007375acd6d0 x27 00000075b39ae000 x28 b4000073b5aa6f50 x29 0000007fc4ac6450 lr 00000072d93d4ef0 sp 0000007fc4ac5440 pc 00000072d93d4ef0 pst 0000000080000000 backtrace: #00 pc 0000000000002ef0 /data/app/~~AFEop-SVX63wreyZzeYp7A==/com.encapsecurity.encap.example.android.testapp-NJtFrXRjua6YVkum0fgwcQ==/base.apk!libencap-android-native-api.so (BuildId: 59ea07c78f55678b6e364a2f67ea8bc42190f7eb) #01 pc 00000000000043c4 /data/app/~~AFEop-SVX63wreyZzeYp7A==/com.encapsecurity.encap.example.android.testapp-NJtFrXRjua6YVkum0fgwcQ==/base.apk!libencap-android-native-api.so (JNI_OnLoad+80) (BuildId: 59ea07c78f55678b6e364a2f67ea8bc42190f7eb) #02 pc 000000000051c1a8 /apex/com.android.art/lib64/libart.so (art::JavaVMExt::LoadNativeLibrary(_JNIEnv*, std::__1::basic_string, std::__1::allocator > const&, _jobject*, _jclass*, std::__1::basic_string, std::__1::allocator >*)+1872) (BuildId: 02bec5940be704b863f6514fc7d81c41) #03 pc 00000000000051c0 /apex/com.android.art/lib64/libopenjdkjvm.so (JVM_NativeLoad+412) (BuildId: e2d871bce04eabb6198cc5c94b2b4059) #04 pc 000000000036095c /data/misc/apexdata/com.android.art/dalvik-cache/arm64/boot.oat (art_jni_trampoline+156) ``` - This is because the native code `libencap-android-api.so` expects a Java package name in the Activity or Application, but obfuscation removes the Java package name. - You can observe this bug with R8 obfuscation in the [Android Gradle Plugin 8](https://developer.android.com/build/releases/past-releases/agp-8-0-0-release-notes). #### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.14.6** | **3.14.8** | | **3.15.4** | **3.15.6** | | **3.16.6** | **3.16.8** | | **3.17.7** | **3.17.12** | | **3.18.7** | **3.18.19** | | Earlier versions | N/A | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) :::note Alternative to upgrading For alternatives to upgrading, see section [Alternative workarounds](#alternative-workarounds) below. ::: ##### Alternative workarounds Alternatively, you can also implement one of the following workarounds to solve the issue: - This bug can be avoided by adding a Proguard rule for the app: ``` -repackageclasses 'com.mypackagename' ``` - This bug can be avoided by disabling R8 full mode in `gradle.properties`: ``` android.enableR8.fullMode=false ``` ### 11.04.2024 #### Patch: Privacy manifest and client debug data :::info Platform: iOS ::: ##### Overview ###### 3.18.3, 3.17.3, 3.16.4 - Added `PrivacyInfo.xcprivacy`: - As of 01.05.2024, Apple has enforced apps to describe their use of the required reason API in their privacy manifest file. - The article [Describing use of required reason API](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api) in the Apple developer documentation warns: > If you upload an app to App Store Connect that uses required reason API without describing the reason in its privacy manifest file, Apple sends you an email reminding you to add the reason to the app's privacy manifest. Starting May 1, 2024, apps that don't describe their use of required reason API in their privacy manifest file aren't accepted by App Store Connect. - If you are using Xcode 15, embed the Encap framework that was dragged in. Navigate to the target's **General** settings, locate **Frameworks, Libraries, & Embedded Content**, then select **Embed & Sign**. This step will enable privacy manifests to be picked up by Xcode's tooling. - Removed `diskSpace`: - In versions 3.16 and above, `diskSpace` is no longer available in our client debug data feature. - This update became essential when reviewing our data usage, particularly for `NSPrivacyAccessedAPICategoryDiskSpace` where the available options did not accurately reflect our circumstances. - In alignment with Apple's guidelines, we have chosen to entirely remove references to diskSpace APIs. ##### Affected versions If your app uses an affected version of the SDK, then you should upgrade it to use the latest, patched version: | **Affected versions** | **Patched version** | | :-- | :-- | | **3.18.2** | **3.18.3** | | **3.17.2** | **3.17.3** | | **3.16.3** | **3.16.4** | | Earlier versions | N/A | ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) :::note Cannot upgrade? If this is not possible, see section [Known limitations and workaround](#known-limitations-and-workaround) below. ::: ##### Known limitations and workaround We have seen that declared use of the reason API in the `PrivacyInfo.xcprivacy` file inside the SDK is not getting taken into evaluation from Apple when sending the app to the App Store for review. We have an ongoing support ticket with Apple and currently assume that it is a bug on Apple's side. If you experience this problem, we suggest that you take what we have declared in the `PrivacyInfo.xcprivacy` file, and add to your `PrivacyInfo.xcprivacy` file until this issue is resolved. If you are using an SDK below version 3.16, then the `PrivacyInfo.xcprivacy` found in newer versions can be used and copied across. In this case, it is expected to be in the root of the `.framework` folder for both architectures. You can download the library from our Nexus partner repository. Change your current dependency to the new version. ## 2023 ### 20.10.2023 #### Release: SDK 3.18 :::info Platform: Android, iOS ::: ##### Overview ###### 3.18 We have released version 3.18 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.18**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-318)   [**iOS SDK 3.18**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-318) :::note Note We have verified this SDK version (3.18) on **iOS 17** and **Android 14**. ::: ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ##### Upcoming changes In the next SDK version (3.20), we will make the following changes: - Bump the minimum supported platform versions to **Android 8.0 (API 26)** and **iOS 14.0**. ### 26.05.2023 #### Release: SDK 3.17 :::info Platform: Android, iOS ::: ##### Overview ###### 3.17 We have released version 3.17 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.17**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-317)   [**iOS SDK 3.17**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-317) ##### What is new? :::warning Important Support for **Android 6.0 (API 23)** has been removed. ::: ###### Google Play Integrity :::info What is Play Integrity? Play Integrity replaces the SafetyNet service, which is being discontinued by Google. You can read more about this in the [Android developer documentation](https://developer.android.com/training/safetynet/deprecation-timeline). ::: We have introduced support for Play Integrity, which is provided by Google as part of the Android platform. This feature lets you enforce the use of trusted Android devices and genuine apps that have been installed from the Google Play Store, and gives your app an equal or higher level of integrity assurance than SafetyNet. As part of rolling out this feature, we are removing SafetyNet support and therefore require current users to migrate to Play Integrity. You can read more about Play Integrity in the [Android developer documentation](https://developer.android.com/google/play/integrity). For more information about app attestation for MobileID, see the [MobileID feature documentation](/docs/mobile-identity/mobileid/features/app-attestation/). ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ### 30.01.2023 #### Release: SDK 3.16 :::info Platform: Android, iOS ::: ##### Overview ###### 3.16 We have released version 3.16 of our SDK for Android and iOS. For an overview of the changes, see the version notes for each platform: [**Android SDK 3.16**](/docs/mobile-identity/encap/release-notes/sdk-android/#sdk-316)   [**iOS SDK 3.16**](/docs/mobile-identity/encap/release-notes/sdk-ios/#sdk-316) ##### What is new? ###### iOS Extension support We have introduced support for iOS extensions, allowing you to extend functionality beyond your app. For example, you can now enable users to add a bank card directly from their Apple Wallet, and authenticate with MobileID through the extension. You can implement any of the existing in-app authentication methods (such as a PIN, or biometrics) for this out-of-app authentication. Our feature guide for iOS extension support is coming soon. To learn more, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ###### iOS Time sensitive notification Apple introduced a new feature in iOS 15 called 'Focus', which is a custom 'Do Not Disturb' mode for different moments of everyday life. When 'Focus' mode is active, most notifications are blocked, including our customer's urgent notifications. You can now give notifications a higher priority (and break notification blocking) by enabling 'time sensitive notifications' in both your application configuration and your iOS app. To enable this, see the `apnsTimeSensitiveInterruptionLevelEnabled` parameter in the [application configuration](/docs/mobile-identity/mobileid/features/application-configuration/#push-notifications). ###### Client server crypto protocol V3 We have made multiple security improvements to the client-server crypto protocol. The most important changes for V3 of the protocol are: - Fixes for a padding oracle attack - Upgrading the AES key sizes to 256bit ##### How to upgrade To get the latest features and security improvements, you need to upgrade your mobile app to use the most recent version of the SDK: [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/) ##### Upcoming changes In the next SDK version (3.17), we will make the following changes: - Remove support for **Android 6.0 (API 23)**. --- ## MobileID service :::info Follow the release notes on this page for the latest updates. ::: ## 2026 ### 06.08.2026 #### MobileID API ##### Generating an event when the device state changes You can now control whether you receive an event when the device state changes by passing the `generateEvent=true` query parameter to the **Update device** operation. If `generateEvent` is omitted, it defaults to `false`, and no event is generated. :::details See endpoint - [Update device](pathname:///apis/mobileid/#tag/Device-management/operation/updateDevice) ::: #### ReuseID API ##### Added MobileID device hash management resource The ReuseID API now includes a new **MobileID device hash management** resource. The new endpoints allow you to retrieve a list of devices associated with a given device hash and lock all devices associated with that hash. :::details See all new endpoints - [Get devices with device hash](pathname:///apis/reuseid/#tag/MobileID-device-hash-management/operation/getDevicesWithDeviceHash) - [Lock devices with device hash](pathname:///apis/reuseid/#tag/MobileID-device-hash-management/operation/lockDevicesWithDeviceHash) ::: ##### Generating an event when the device state changes You can now control whether you receive an event when the device state changes by passing the `generateEvent=true` query parameter to the **Update device** operation. If `generateEvent` is omitted, it defaults to `false`, and no event is generated. :::details See endpoint - [Update device](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/updateDevice) ::: #### MobileID Admin API ##### Updated Statistics resource We have updated the **Statistics** resource in the MobileID Admin API. The **Get devices with device hash** and **Lock devices with device hash** operations have moved to the **MobileID device hash management** resource in the ReuseID API. For links to the new endpoints, see [Added MobileID device hash management resource](#added-mobileid-device-hash-management-resource) above. The **Statistics** resource now contains the following operations: :::details See Statistics endpoints - [Get detailed device statistics](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getAccountStatistics) - [Get device hash statistics](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getDeviceHashStatistics) - [Get active users and devices (by day count)](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getUserAccountStatisticsByNumberOfDays) - [Get active users and devices (by date interval)](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getUserAccountStatistics) ::: ##### Changed context path for Get device hash statistics To align with our other services, we have changed the context path for the **Get device hash statistics** operation from `devicehashes` to `device-hashes`. :::warning Backward compatibility This context path change is not backward compatible. If your integration calls this operation, update it to use the new `device-hashes` context path. No action is required if you access this operation only through the Signicat Dashboard, as the Dashboard already uses the new context path. ::: ### 03.08.2026 #### MobileID Admin API ##### Added `algorithm` property for E2E key creation The [Add E2E key](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/addE2EKey) endpoint now supports the `algorithm` property. With this property, you can explicitly select the algorithm used for key exchange between the SDK and the server. The default algorithm for newly generated E2EE keys has changed to `X25519`. :::warning Important - For apps using an SDK version earlier than 3.22, generate E2EE keys with the `SECT233K1` algorithm. - Before you upgrade your app to SDK 3.22 or later, you must rotate your E2EE key to one that uses the `X25519` algorithm. Follow the [key rotation process](/docs/mobile-identity/mobileid/features/end-to-end-encryption/#key-rotation) to avoid downtime. ::: :::info Want to learn more? To learn more, see our [End-to-end encryption](/docs/mobile-identity/mobileid/features/end-to-end-encryption/) feature documentation. ::: ### 30.07.2026 #### Signicat Dashboard ##### Hardware-protected key validation strategy It is now possible to set the hardware-protected key validation strategy in the Signicat Dashboard. To configure it yourself, go to: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour). 2. Select the **Hardware key validation** tab. 3. Select the desired hardware-protected key validation strategy, then click **Save**. :::info Want to learn more? To learn more, see our [Hardware-protected keys](/docs/mobile-identity/mobileid/features/hardware-protected-keys/) feature documentation. ::: ### 28.07.2026 #### MobileID Admin API ##### Added hardware-protected key validation strategy We have added more options for the hardware-protected key validation strategy. Now, you can choose between either: | **Validation strategy** | **Description** | | :-- | :-- | | `REQUIRED_IF_SUPPORTED` | Enforces hardware key validation if the device supports hardware keys.**Note**: This is the default strategy. | | `REQUIRED` | Enforces hardware key validation for all devices. | This is configured with the `hwKeyValidationStrategy` property in your application configuration, using the **MobileID Admin API**. :::info Want to learn more? To learn more, see the: - [Hardware-protected keys](/docs/mobile-identity/mobileid/features/hardware-protected-keys/) feature documentation. - [Update properties of application configuration](pathname:///apis/mobileid-admin/#tag/Application-configuration/operation/updateAppConfigurationProperties) endpoint in our **MobileID Admin API** reference documentation. ::: ### ### 19.06.2026 #### Signicat Dashboard ##### Lock scope It is now possible to configure the lock scope in the Signicat Dashboard. :::note What is the lock scope? The lock scope determines the lock behaviour following failed authentication attempts. This can be either: - **Device**: Locks the entire device. - **Authentication method**: Locks only the authentication used. ::: To configure it yourself, go to: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour). 2. Select the **Authentication** tab, then navigate to the **Lock scope** section on the page. 3. Use the radio buttons to select the desired lock scope, then click **Save**. :::info Want to learn more? To learn more, see the `lockScope` property in the [Application behaviour](/docs/mobile-identity/mobileid/features/application-configuration/#application-behaviour) section of our **Application configuration** feature documentation. ::: ### 03.06.2026 #### MobileID Admin API ##### Added resource for 'Risk indicators configuration' Our MobileID Admin API is extended with a new resource for **Risk indicators configuration**. The new endpoints allow you to retrieve and update your account's risk indicators configuration. You can read more about this in our MobileID Admin API reference documentation using the links below. :::details See all new endpoints - [Get risk indicators configuration](pathname:///apis/mobileid-admin/#tag/Risk-indicators-configuration/operation/getRiskIndicators) - [Update risk indicators configuration](pathname:///apis/mobileid-admin/#tag/Risk-indicators-configuration/operation/getRiskIndicators) ::: :::info Want to learn more? To learn more, see our [Risk indicators](/docs/mobile-identity/mobileid/features/risk-indicators/) feature documentation. ::: ### 02.06.2026 #### Signicat Dashboard ##### Device hash risk indicator It is now possible to identify and prevent fraud by reviewing or locking flagged device hashes in the Signicat Dashboard. :::note What is a device hash? The device hash is designed to be persistent and unique for a mobile device within your app. If the same device hash is present across multiple users, it could suggest that one malicious individual is using a single device to gain access to numerous accounts for unauthorised activities and account takeovers. ::: On this new page, you can see: - The number of unique device hashes. - The number of active users. - An overview of flagged device hashes. You can also find detailed information about the users and devices associated with the flagged device hashes, such as when the device was last used and its status. To test it yourself, see the [Device hash](https://dashboard.signicat.com/mobileid/risk-indicators/device-hash) page under the **Risk indicators** section in the Signicat Dashboard! :::info Want to learn more? To learn more, see the [Device hash](/docs/mobile-identity/mobileid/features/risk-indicators/device-hash.mdx) page in our **Risk indicators** feature documentation. ::: ### 28.05.2026 #### Signicat Dashboard ##### Extended scope of transaction statistics On the **MobileID** [Overview](https://dashboard.signicat.com/mobileid/overview) page in the Signicat Dashboard, you can see transaction statistics for MobileID devices. Previously, only statistics for for MobileID customers using the **MobileID REST API** were shown. In this release, we have extended the scope to include device statistics for: - ReuseID customers using MobileID device authentication through our **ReuseID REST API** or **eID and Wallet Hub**. - MobileID customers using MobileID authentication through our **eID and Wallet Hub**. :::info What are transaction statistics? These statistics provide you with an activity overview of the following for the last 30 days: - Authentication count - Authentication success rate - Registration count - Active users - Active devices ::: ### 27.05.2026 #### MobileID Admin API ##### Added resource for 'Statistics' Our MobileID Admin API is extended with a new resource for **Statistics**. The new endpoints allow you to retrieve statistics about devices, users and device hashes, in addition to reviewing or locking flagged device hashes. You can read more about this in our MobileID Admin API reference documentation using the links below. :::details See all new endpoints - [Get detailed device statistics](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getAccountStatistics) - [Get device hash statistics](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getDeviceHashStatistics) - [Get devices with device hash](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getLiveDeviceHashStatistics) - [Lock devices with device hash](pathname:///apis/mobileid-admin/#tag/Statistics/operation/lockAllDevicesForDeviceHash) - [Get active users and devices (by day count)](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getUserAccountStatisticsByNumberOfDays) - [Get active users and devices (by date interval)](pathname:///apis/mobileid-admin/#tag/Statistics/operation/getUserAccountStatistics) ::: ### 21.04.2026 #### Signicat Dashboard ##### Device statistics It is now possible to view device statistics in the Signicat Dashboard, for your active MobileID devices. :::note Active MobileID devices Device statistics are for active MobileID devices. A MobileID device is active if it has performed at least one operation in the last six months. ::: On this new page, you can find the following information: - Distribution of devices by SDK version and platform - Device OS version - Device manufacturer - Device model To test it yourself, see the [Statistics](https://dashboard.signicat.com/mobileid/statistics/devices) page in the Signicat Dashboard! ## 2025 ### 11.11.2025 #### Removed passport scan feature We have now completely removed the MobileID passport scan feature, that was deprecated on [30.10.2024](#30102024). To replace this feature, you can use our [ReuseID](/docs/reuseid/) solution instead. :::info What is ReuseID? Our ReuseID solution allows you to perform ID document and biometric verification for either onboarding end-users to MobileID or existing MobileID users. ::: ### 03.11.2025 #### MobileID API, MobileID Admin API, Signicat Dashboard ##### New risk data attributes We have extended the set of device risk attributes that can be collected during a transaction. These attributes give you a deeper insight into the state of the device at the time of use: | **Category** | **Description** | | :-- | :-- | | Sensor insights | These attributes give you access to motion and environmental sensor data, to support advanced behavioural or situational analysis: `magnetometer`, `gravity`, `barometer`. | | Network context | These attributes enable you to evaluate the trust level of the network connection and identify potential spoofing or untrusted Wi-Fi environments: `ssid`, `bssid`, `isVpnEnabled`, `isProxyEnabled`. | | Device integrity | These attributes enable you to detect signs of tampering or unsafe configurations that may indicate a compromised device: `isDeveloperMode`, `isOverlayDetected`. | | Locale & environment | These attributes enable you to gain better understanding of the end-user's regional context and time-based patterns for anomaly detection: `timeZone`, `locale`. | To collect these new risk attributes, you need to both: - Upgrade your mobile app to use version 3.21 of our SDK. - Enable them using the MobileID risk data feature in the Signicat Dashboard. [**Upgrade guide**](/docs/mobile-identity/mobileid/upgrade-guide/)   [**Signicat Dashboard**](https://dashboard.signicat.com/mobileid/features/risk-data) :::info Want to learn more? To learn more about the new risk attributes, see the [Risk attributes](pathname:///apis/mobileid/#section/Common-concepts/Risk-attributes) table in the **Common concepts** of our MobileID API reference documentation. ::: ### 28.10.2025 #### MobileID API ##### Recovery method name change To have a consistent naming scheme, we have changed the name of recovery method `CLOUD_BACKUP` to `CLOUD_BACKUP_RECOVERY_CODE`. To learn more, see our MobileID API reference documentation: - [**Get account recovery**](pathname:///apis/mobileid/#tag/Account-recovery/operation/getAccountRecovery) - [**Get device details**](pathname:///apis/mobileid/#tag/Device-management/operation/getDevice) ##### Concurrency improvements We have improved the database lock handling so that multiple concurrent requests for the same device get a proper error message, instead of an HTTP 500 error. To learn more, see our MobileID API reference documentation: - [**Add registrations**](pathname:///apis/mobileid/#tag/Registration/operation/addRegistration) - [**Get registrations**](pathname:///apis/mobileid/#tag/Registration/operation/getRegistration) #### Audit logs ##### Renamed audit event types We have rewritten most event type names to make them more readable. They now follow a general pattern of `ORIGIN_ACTION_EVENT`. To see all changes, together with the previous naming scheme, see the Signicat developer documentation. - [**Encap service audit event types**](pathname:///docs/mobile-identity/encap/server/manual/encap-server-logs/#event-type) - [**Signicat audit log service docs**](pathname:///docs/dashboard/settings/audit-logs/) ##### Purpose field removed We have removed the purpose field, as the purpose is already a part of the event type name. ### 28.08.2025 #### MobileID API ##### Deprecated endpoint for 'User' resource We have deprecated the [**Get proofings for user**](pathname:///apis/mobileid/#tag/User/operation/getProofings) endpoint for the **User** resource in the MobileID API. This endpoint will be completely removed in the near future. ### 01.08.2025 #### MobileID API ##### Removed endpoint for 'Passport scan' resource We have removed the **Get full final result of the passport scan** endpoint for the **Passport scan** resource in the MobileID API. If you need to get the full final result of an executed passport scan, then you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### 10.07.2025 #### End-of-life for passport scan feature The MobileID passport scan feature that was deprecated on [30.10.2024](#30102024) will be removed completely on 01.11.2025. To replace this feature, you can use our [ReuseID](/docs/reuseid/) solution instead. ### 08.07.2025 #### MobileID API ##### Account recovery with server-side face authentication Our [Account recovery](/docs/mobile-identity/mobileid/features/account-recovery) feature enables your end-users to recover their account when they have lost access to it, using your app. We have now improved our account recovery feature by adding support for [server-side face authentication](/docs/mobile-identity/mobileid/features/face-authentication/). This authentication method is: - More user-friendly, as there is no recovery code to remember. - More secure, as there is no recovery code which can be shared. To retrieve information about how the account recovery was performed, the **Get details of account recovery** response has been extended with two new properties: `recoveryMethod` and `recoveryStatus`. :::details Want to learn more? - See the [Account recovery](/docs/mobile-identity/mobileid/features/account-recovery) feature documentation. - See the [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/) feature documentation. - See the [Get details of account recovery](pathname:///apis/mobileid/#tag/Account-recovery) endpoint in our MobileID API reference documentation. ::: ### 27.06.2025 #### MobileID API #### Deprecated lock reason attribute We have removed the `lockReason` attribute from the `device` object. To get the lock reason, you must use the [Get device](pathname:///apis/mobileid/#tag/Device-management/operation/getDevice) endpoint in the MobileID **Device management** API. The lock reason is returned in the `deviceDetails` object, so you must use query parameter `detailed=true`. :::note Note Although it is still possible to pass the `lockReason` attribute in the request body when using the [Update device](pathname:///apis/mobileid/#tag/Device-management/operation/updateDevice) endpoint, it is no longer applied. ::: ### 21.05.2025 #### MobileID API ##### Removed device name limitations We have removed the character set limitations for the device name. This means that there are no longer restrictions on what letters, digits or special characters the device name can contain or must start with. :::note Note The device name must still not exceed the maximum character length. ::: ### 01.04.2025 #### MobileID API, MobileID Admin API, Signicat Dashboard ##### Removed risk attribute We have removed the obsolete risk attribute `isUnknownSourcesEnabled`. This means that: - The MobileID API can no longer return this in a response as a part of the `riskAttributes` object. - You can no longer set this risk attribute in the `enabledRiskData` in your application configuration with the MobileID Admin API or the Signicat Dashboard. :::details Want to learn more? - See the [Risk attributes](pathname:///apis/mobileid/#section/Common-concepts/Risk-attributes) table in the **Common concepts** of our MobileID API reference documentation. - See the [Update properties of application configuration](pathname:///apis/mobileid-admin/#tag/Application-configuration/operation/updateAppConfigurationProperties) endpoint in our MobileID Admin API reference documentation. - See the MobileID [Risk data](https://dashboard.signicat.com/mobileid/features/risk-data) page in the Signicat Dashboard. ::: ### 19.03.2025 #### Signicat Dashboard ##### Quick configuration in the Signicat Dashboard On the **Details** page, we have added a button that allows you to quickly configure the Authenticator App for your account with a QR code. To test it yourself, see the [Details](https://dashboard.signicat.com/mobileid/details) page! ### 12.03.2025 #### Signicat Dashboard ##### Try out MobileID in the Signicat Dashboard It is now possible to try out MobileID in the Signicat Dashboard. On the new **Try it out** page, you can: - Install our Authenticator App on iOS or Android by scanning a QR code. - Scan a QR code to configure the app for your account. - Carry out registrations and authentications. - Manage your devices. To test it yourself, see the [Try it out](https://dashboard.signicat.com/mobileid/try-it-out) page! ### 07.03.2025 #### Signicat Dashboard ##### Test MobileID as an eID in the Signicat Dashboard It is now possible to test out MobileID as an eID with the Authorization Code Flow using the Signicat Dashboard. To learn how to do this, see our MobileID [Test it out](/identity-methods/mobileid/test/signicat-dashboard.mdx) documentation. ### 06.03.2025 #### Signicat Dashboard ##### Simplified configuration of face authentication feature In this release, we have simplified the way in which you configure the face authentication feature for MobileID in the Signicat Dashboard. :::info What does this mean? This means that you no longer have to enable/disable the feature using the **Server-side face** page. Now, you only need to configure it as an allowed authentication method. ::: To configure face authentication: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Application behaviour**](https://dashboard.signicat.com/mobileid/features/application-behaviour), then select the **Authentication** tab. 2. Use the check boxes to enable server-side face as an authentication method, then click **Save**. To learn more about our face authentication feature, see our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx) feature documentation. ### 27.02.2025 #### MobileID Admin API ##### End-to-end (E2E) keys API extended Our MobileID Admin [End-to-end (E2E) keys](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys) API is extended with endpoints that allow you to create and manage your E2E keys. You can read more about this in our MobileID Admin API reference documentation: :::details See all new endpoints - See the [Update E2E key](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/updateE2EKeyStatus) endpoint. - See the [Add E2E key](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/addE2EKey) endpoint. - See the [Get E2E key](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/getE2EKey) endpoint. - See the [Delete E2E key](pathname:///apis/mobileid-admin/#tag/End-to-end-(E2E)-keys/operation/deleteE2EKey) endpoint. ::: ### 26.02.2025 #### MobileID API ##### Updated signature request parameter From this release, the signature request parameter `signedJwtCertificateOption` no longer supports values `SINGLE` or `CHAIN`. - For backwards compatibility, you can still use this parameter with value `NONE`. - When this parameter is not passed in the signature request, the default value is still `NONE`. To learn more about our signature operation, see our [Signature](/docs/mobile-identity/mobileid/features/signature.mdx) feature documentation. ## 2024 ### 19.12.2024 #### MobileID with Authorization Code Flow released You can now access MobileID features using the OpenID Connect (OIDC) protocol with the Authorization Code Flow. To learn more about this see our [MobileID Authorization Code Flow](/identity-methods/mobileid/integration-guides/oidc/authorization-code-flow) documentation. ### 31.10.2024 #### Face authentication feature released In this release, we have added a new authentication method in MobileID called Face Authentication. This authentication method performs a biometric authentication that is verified on the server side, in addition to a **Liveness check**. To learn more about our face authentication feature: - See our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx) feature documentation. - See our **Application configuration** feature documentation: - New property for enabling/disabling face authentication in the [Face authentication](/docs/mobile-identity/mobileid/features/application-configuration.mdx#face-authentication) section. - New allowed value for the `allowedAuthMethods` and `allowedAuthMethodsForAuthAndActivate` properties in the [Application behaviour](/docs/mobile-identity/mobileid/features/application-configuration.mdx#application-behaviour) section. ### 30.10.2024 #### Passport scan is replaced by ReuseID The MobileID Passport scan feature is now deprecated, and is replaced by our [ReuseID](/docs/reuseid/) solution. :::note What does this mean? - You can use ReuseID to perform ID document and biometric verification for either onboarding of users to MobileID or on existing MobileID users. - We will remove the APIs for starting a new passport scan on a MobileID user. - All previous passport scan processes will remain linked to the user. - The APIs used to fetch a full passport scan result will continue to be available. ::: ### 22.10.2024 #### MobileID events ##### Added event for account recovery state change In this release, we have added a new MobileID event which you can subscribe to, called **Account recovery state change** (`account-recovery.state.change`). If subscribed, then you will receive this event whenever an account recovery is added or deleted by an end-user on their device. :::info Want to learn more? You can learn more about MobileID events in the [Events](pathname:///apis/mobileid/#section/Using-this-API/Events) section of our MobileID API reference documentation. ::: ### 17.10.2024 #### MobileID API ##### Risk Data Previously, the MobileID authentication response only returned risk data if the operation completed successfully. In this release, risk data is now also returned when the operation completes with an error status or is expired. ### 03.07.2024 #### MobileID API ##### Account recovery API added Our MobileID API is extended with a new API for **Account recovery**. The new **Get details of account recovery** endpoint allows you to fetch the details of an account recovery carried out for a device. You can read more about this in our MobileID API reference documentation: - See the [Account recovery](pathname:///apis/mobileid/#tag/Account-recovery) API. - See the [Get details of account recovery](pathname:///apis/mobileid/#tag/Account-recovery/operation/getAccountRecovery) endpoint. #### MobileID events ##### Added event for device state change In this release, we have added a new MobileID event which you can subscribe to called **Device state change** (`device.state.change`). You will receive this event whenever a device is deactivated or locked externally. :::note Example If subscribed, then you will receive this event if a device is locked due to too many failed authentication attempts. ::: :::info Want to learn more? You can learn more about MobileID events in the [Events](pathname:///apis/mobileid/#section/Using-this-API/Events) section of our MobileID API reference documentation. ::: ### 28.06.2024 #### Signicat Dashboard ##### Transaction statistics MobileID is now updated with transaction statistics in the Signicat Dashboard. On the new MobileID [**Overview**](https://dashboard.signicat.com/mobileid/overview) page in the Signicat Dashboard, you can now view key statistics for your MobileID account, and visualise them in a graph. These statistics provide you with an activity overview of the following for the last 30 days: - Authentication count - Authentication success rate - Registration count ##### Improved usability We have also improved the usability of MobileID in the Signicat Dashboard: - The page containing details about your MobileID account in the Signicat Dashboard is now called [**Details**](https://dashboard.signicat.com/mobileid/details) instead of **Overview**. - The **Active devices** and **Active users** statistics have now been moved to the new key statistics **Overview** page. ### 13.06.2024 #### MobileID API ##### Added field for requested user attributes In this release, we have extended the `operationProperties` of registration, authentication and signature requests with a new field called `requestedUserAttributes`. In this field, you can list the user attributes to be included in the response when the operation completes successfully. You can read more about this in our MobileID API reference documentation: :::details See all extended endpoints - See the [Start registration](pathname:///apis/mobileid/#tag/Registration/operation/addRegistration) endpoint. - See the [Start authentication](pathname:///apis/mobileid/#tag/Authentication/operation/addAuthentication) endpoint. - See the [Start signing](pathname:///apis/mobileid/#tag/Signature/operation/addSignature) endpoint. - See the [Get state of ongoing registration](pathname:///apis/mobileid/#tag/Registration/operation/getRegistration) endpoint. - See the [Get state of ongoing authentication](pathname:///apis/mobileid/#tag/Authentication/operation/getAuthentication) endpoint. - See the [Get state of ongoing signing](pathname:///apis/mobileid/#tag/Signature/operation/getSignature) endpoint. ::: ### 05.04.2024 #### MobileID CIBA ##### Added field for user and transaction segmentation In this release, we have added a new claim called `mobileid_user_segment`. This claim belongs to the `mobileid_extra` scope, and is returned in the ID token part of the token response. This is an optional field configured on user accounts, which allows you to segment end-users and corresponding transactions. You can also use it for statistics. To learn more about this, see [MobileID extra scope](/identity-methods/mobileid/integration-guides/oidc/ciba-flow/attributes-reference/#mobileid-extra-scope) claims in our MobileID CIBA documentation. ### 19.03.2024 #### MobileID API ##### Added field for user and transaction segmentation In this release, we have extended all requests and responses containing user data with a new field called `segment`. This is an optional field configured on user accounts, which allows you to segment end-users and corresponding transactions. You can also use it for statistics. You can read more about this in our MobileID API reference documentation: :::details See all extended endpoints - See the [Create user](pathname:///apis/mobileid/#tag/User/operation/addUser) endpoint. - See the [Resolve external reference](pathname:///apis/mobileid/#tag/User/operation/resolveUserIDByExtref) endpoint. - See the [Get user](pathname:///apis/mobileid/#tag/User/operation/getUser) endpoint. - See the [Update user](pathname:///apis/mobileid/#tag/User/operation/updateUser) endpoint. - See the [Get state of ongoing registration](pathname:///apis/mobileid/#tag/Registration/operation/getRegistration) endpoint. - See the [Get state of ongoing authentication](pathname:///apis/mobileid/#tag/Authentication/operation/getAuthentication) endpoint. - See the [Get state of ongoing signing](pathname:///apis/mobileid/#tag/Signature/operation/getSignature) endpoint. - See the **Get state of ongoing passport scan** endpoint. ::: ### 08.03.2024 #### MobileID Admin API ##### Accounts API extended Our MobileID [Accounts API](pathname:///apis/mobileid-admin/#tag/Accounts) is extended with a new endpoint that allows you to change the state of your account. You can read more about this in our MobileID Admin API reference documentation: - See the [Update account](pathname:///apis/mobileid-admin/#tag/Accounts/operation/updateAccount) endpoint. ### 20.02.2024 #### MobileID Admin API ##### Implemented cleanup of inactive devices In this release, we have implemented cleanup of inactive devices. This means that we remove devices that have not be used for an extended period of time. The default inactive period is set to `365` days; this starts from the time when the device was last used to carry out an operation. - To see the value configured for your account, see the [Details](https://dashboard.signicat.com/mobileid/details) page in the Signicat Dashboard. - To change this value, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::info Want to learn more? To learn more, see the [Cleanup of inactive devices](/docs/mobile-identity/mobileid/features/application-configuration.mdx#cleanup-of-inactive-devices) section in our **Application configuration** feature documentation. ::: ##### Updated values for activation code length We have updated the minimum and default values for the application configuration property `activationCodeLength`: - The minimum length is now `6`. - The default length is now `10`. To learn more about this, see the [Application behaviour](/docs/mobile-identity/mobileid/features/application-configuration.mdx#application-behaviour) section in our **Application configuration** feature documentation. ### 13.02.2024 #### Signicat Dashboard ##### Updated MobileID with new features In this release, we have updated MobileID with many new features in the [Signicat Dashboard](https://dashboard.signicat.com/mobileid/)! You can now configure: - Account recovery - App attestation - Application behaviour - Geofencing - Push messaging - Risk data You can read about how to test MobileID out in our [Quick start guide](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication.mdx). ### 11.01.2024 #### MobileID API ##### User API In our MobileID [User API](pathname:///apis/mobileid/#tag/User), we have now removed the previously deprecated **Resolve external reference** endpoint which used the HTTP GET method. This means that you can now only use the newer [Resolve external reference](pathname:///apis/mobileid/#tag/User/operation/resolveUserIDByExtref) endpoint which uses the HTTP POST method. :::tip Why have we done this? You can read about why the previous endpoint was deprecated and improved in our [31.10.2023](#31102023) release notes. ::: ## 2023 ### 04.12.2023 #### MobileID API ##### Authentication and signature responses extended Responses for successfully completed MobileID authentication and signature operations are extended with a new field called `clientData`. This field contains data that the client application has optionally passed at the time of the authentication, in the SDK `startAuthentication` call. ##### Device management API extended Our MobileID [Device management API](pathname:///apis/mobileid/#tag/Device-management) is extended with a new set of endpoints that allow you to manage geofencing settings per device. You can read more about this in our MobileID API reference documentation: - See the [Get geofencing settings](pathname:///apis/mobileid/#tag/Device-management/operation/getGeofencingSettings) endpoint. - See the [Update geofencing settings](pathname:///apis/mobileid/#tag/Device-management/operation/putGeofencingSettings) endpoint. - See the [Delete geofencing settings](pathname:///apis/mobileid/#tag/Device-management/operation/deleteGeofencingSettings) endpoint. ### 24.11.2023 #### MobileID available in the Signicat Dashboard MobileID is now available in the [Signicat Dashboard](https://dashboard.signicat.com/mobileid/). Here, you can: - Create an account to use with MobileID in a single click. - Find useful information about your MobileID account. - List signing certificates and public keys linked to your MobileID account. You can read about how to test MobileID out in our [Quick start guide](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication.mdx). ### 20.11.2023 #### Geofencing feature released Our new geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. If you have configured our geofencing feature in your application configuration, then you can now see the geofencing object as a part of the operation response. To learn more about our geofencing feature: - See the [Geofencing](/docs/mobile-identity/mobileid/features/application-configuration/#geofencing) section in our **Application configuration** feature documentation. - See the geofencing response object for any GET operation in our [MobileID API reference documentation](/apis/mobileid/). ### 16.11.2023 #### Default risk attributes We now collect a set of default risk attributes for debugging purposes. This means that now, some risk data is always collected and returned, regardless of how your application configuration is configured. You can find a list of what risk data is always enabled in the MobileID API reference documentation: - See [risk attributes](pathname:///apis/mobileid/#section/Common-concepts/Risk-attributes) in the **Common concepts** section. To learn more about risk data: - See the [Risk data](/docs/mobile-identity/mobileid/features/application-configuration/#risk-data) section in our **Application configuration** feature documentation. ### 09.11.2023 #### MobileID Admin API ##### Application configuration API added Our MobileID Admin API is extended with a new API for **Application configuration**. The new endpoints allow you to administer and manage your [application configuration](/docs/mobile-identity/mobileid/features/application-configuration.mdx). You can read more about this in our MobileID Admin API reference documentation: - See the [Application configuration](pathname:///apis/mobileid-admin/#tag/Application-configuration) API. ##### APNs token API added Our MobileID Admin API is extended with a new API for **APNs tokens**. These new endpoints allow you to create and manage your Apple Push Notification service (APNs) tokens. You can read more about this in our MobileID Admin API reference documentation: - See the [APNs token](pathname:///apis/mobileid-admin/#tag/APNs-tokens) API. ### 31.10.2023 #### MobileID API ##### User API improved Our MobileID [User API](pathname:///apis/mobileid/#tag/User) is improved with a new endpoint to resolve the user ID based on an external reference. :::tip Why have we done this? The new endpoint improves security and flexibility, as the external reference is now passed in the JSON body when executing the operation. ::: In summary, we have: - Added a new **Resolve external reference** endpoint which uses the HTTP POST method. - Deprecated the existing **Resolve external reference** endpoint which uses the HTTP GET method. You can read more about this in our MobileID API reference documentation: - See the [Resolve external reference](pathname:///apis/mobileid/#tag/User/operation/resolveUserIDByExtref) endpoint. ### 25.10.2023 #### MobileID API ##### User API extended Our MobileID [User API](pathname:///apis/mobileid/#tag/User) is extended with a new endpoint that allows you to get device transactions for all of the end-user's devices. You can read more about this in our MobileID API reference documentation: - See the [Get transactions for user](pathname:///apis/mobileid/#tag/User/operation/getUserTransactions) endpoint. ### 06.10.2023 #### MobileID API ##### Device management API extended Our MobileID [Device Management API](pathname:///apis/mobileid/#tag/Device-management) is extended with a new endpoint that allows you to get device transactions for an end-user's device. You can read more about this in our MobileID API reference documentation: - See the [Get device transactions](pathname:///apis/mobileid/#tag/Device-management/operation/getDeviceTransactions) endpoint. ##### Registration and Device management APIs improved The length and character set for the device name is now validated. You can read more about this in our MobileID API reference documentation: - See the [Start registration](pathname:///apis/mobileid/#tag/Registration/operation/addRegistration) endpoint. - See the [Update device](pathname:///apis/mobileid/#tag/Device-management/operation/updateDevice) endpoint. ### 05.05.2023 #### MobileID Admin API released Our MobileID Admin API allows you to manage and administer your MobileID account. To learn more about this API: - See our [MobileID Admin API reference documentation](/apis/mobileid-admin/). ### 02.04.2023 #### Passport scan feature released Our new passport scan feature allows you to validate the authenticity of an end-user's passport and collect passport attributes. To learn more about our passport scan feature: - See our **Passport scan** feature documentation. - See our **MobileID API reference documentation**. --- ## Upgrade guide ## About upgrading MobileID Our MobileID product uses our Encap SCA product, which consists of two components: - A **backend server**, hosted and maintained by Signicat. - A **client SDK**, that you as the customer integrate into your mobile application. ### Backend server Our MobileID product upgrades its Encap SCA server approximately three times a year. We follow the same release cycle as Encap SCA to ensure that the service is continuously improved and that your security requirements are fulfilled. ### Client SDK It is your responsibility to upgrade the client SDK. We will notify you when a new version of the client SDK is available for upgrade. These upgrades keep you up to date with security improvements and new features. :::info Want to learn more? You can also find related information on the MobileID [Release notes](/docs/mobile-identity/mobileid/release-notes) page. ::: ### When should I upgrade? MobileID supports two-years backwards compatibility between the Encap SCA server and the client SDK. As MobileID is a security product, we recommend that you aim to run on the latest version of the SDK, and at least upgrade the SDK twice a year so that you do not fall behind. If you do not upgrade in time, then your mobile authentication will stop working. ## Upgrade plan In the sections below, you can read about what Encap SCA server and client SDK versions MobileID currently supports, and what the preliminary upgrade plan looks like for the future. ### Current version MobileID currently uses and supports the following Encap SCA versions: :::CustomTable{tableName="MobileID upgrade plan" columnWidths="32% 34% 34%"} | **Current Encap server version** | **Minimum Encap SDK version** | **Latest Encap SDK version** | | :-- | :-- | :-- | | 3.22 | 3.18 | 3.22 | ::: :::details What does this mean? For example, if MobileID currently uses release version **3.22** of the Encap SCA server, it only supports Encap SCA client SDK versions **3.18** to **3.22**. If you app uses Encap SCA client SDK version **3.17**, then you would need to upgrade it to a newer version. ::: ### Future versions The table below shows the preliminary upgrade plan for the MobileID service: :::CustomTable{tableName="MobileID upgrade plan"} | **MobileID service upgrade** | **Encap SCA server version** | **Compatible Encap SCA client versions** | **Minimum Android version** | **Minimum iOS version** | | :-- | :-- | :-- | :-- | :-- | | Q1 2027* | 3.23 | 3.19 to 3.23 | 10.0 (API 29) | 16.0 | | JUL 2026 | 3.22 | 3.18 to 3.22 | 9.0 (API 28) | 15.0 | | OCT 2025 | 3.21 | 3.17 to 3.21 | 9.0 (API 28) | 15.0 | | APR 2025 | 3.20 | 3.15 to 3.20 | 9.0 (API 28) | 14.0 | | JUL 2024 | 3.19 | 3.14 to 3.19 | 8.0 (API 26) | 14.0 | | OCT 2023 | 3.18 | 3.12 to 3.18 | 7.0 (API 24) | 12.0 | | MAY 2023 | 3.17 | 3.11 to 3.17 | 7.0 (API 24) | 12.0 | | JAN 2023 | 3.16 | 3.10 to 3.16 | 6.0 (API 23) | 12.0 | ::: :::note *Future upgrade dates are tentative. ::: :::tip Our recommendation We recommend upgrading your apps to use the latest Encap SCA client version as soon as possible, even if backwards compatibility indicates that it is possible to keep using the current version. ::: ## How do I upgrade? :::note Accessing the SDKs If you are adding the SDK to your application for the first time, then see the **Getting started** pages for [Android](/docs/mobile-identity/encap/sdk-android/getting-started/#add-the-sdk-to-your-application) and [iOS](/docs/mobile-identity/encap/sdk-ios/getting-started/#add-the-sdk-to-your-application). You need login credentials to access the client SDKs from our Nexus repository. To gain access, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: Most client SDK upgrades require minimal code changes: ### Upgrade Android client SDK 1. Determine if any additional changes are required when upgrading to your desired version. For an overview, see the [Android SDK](/docs/mobile-identity/encap/release-notes/sdk-android/) page in our **Release notes**. 2. Update the version number of the dependency in your app's build file. ### Upgrade iOS client SDK 1. Determine if any additional changes are required when upgrading to your desired version. For an overview, see the [iOS SDK](/docs/mobile-identity/encap/release-notes/sdk-ios/) page in our **Release notes**. 2. Navigate to our [Nexus repository](https://nexus.pub.encap.no/#browse/browse:MobileID-partner:com%2Fencapsecurity%2Fencap-ios-swift-api) and enter your Nexus repository login credentials. 3. Download the `.zip` file corresponding to the desired version, then unzip it. 4. Replace the existing `EncapSwiftAPI.xcframework` file in your project's directory with the new one that you downloaded. ## MobileID status updates To get email notifications about planned maintenance windows and updates on any activity affecting the MobileID product, you can subscribe to the [Signicat status page](https://status.signicat.com/). - To configure your subscription for MobileID, you need to select the **MobileID** component when you set up your subscription. - If you consume MobileID through our eID and Wallet Hub (OIDC CIBA), then you must also select **MobileID (CIBA)** under the **eID Connections** component. --- ## Account recovery(Use-cases) ## Use case Your end-user has lost access to your mobile app. This can happen if: - The app has been deleted from the device. - Your end-user has lost their device or obtained a new one. - The old device has stopped working. You want to easily recover this end-user to a new installation of the app, so that they can get access to your services again. The account recovery has to be secure whilst still offering a positive and seamless user experience, and avoid the additional cost of having the end-user go through a full onboarding again. ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. 1. Jane loses her device on a boat trip, and therefore has to buy a new device. 2. Jane installs all of her favourite apps from a cloud backup, including your app. 3. Jane opens your app for the first time on the new device. 4. Your app welcomes Jane back, and asks her to authenticate so that she can recover her account on the new device. 5. Jane performs a [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx) in your app. 6. Jane activates new credentials by selecting a new PIN and enables biometrics. Jane can use these credentials to authenticate and authorise future operations. :::note Success! Jane has now securely recovered her account, and can now access your services on the new device. ::: :::tip Why face authentication instead of Face ID? In some use cases, native biometrics such as Face ID will not work, and so server-side biometrics such as face authentication can be leveraged instead. You can read about the differences between Face ID and face authentication in our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx#what-is-the-difference-between-face-id-and-face-authentication) feature documentation. ::: ## What it looks like The following diagram illustrates what it could look like to perform an account recovery with MobileID, from the perspective of your end-users. Diagram showing end-user flow for account recovery :::info Interactive flow For an interactive flow of account recovery with face authentication, see our [Figma prototype](https://www.figma.com/proto/weohzGQQacg4K8ZOZ5p4Zt/MobileID?page-id=5616%3A10660&node-id=5616-16688&viewport=608%2C373%2C0.68&t=FRNEYvAlTbJvdzc4-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=5616%3A16688). You can either click the app's interface, or use the arrows below the phone. ::: ## Implementation To recover your end-users with 2FA, you have to implement our account recovery feature. Account recovery supports both the server-side face authentication and recovery code authentication methods. :::info Want to learn more? To learn more about this feature and how to configure it, see our [Account recovery](/docs/mobile-identity/mobileid/features/account-recovery) feature documentation. ::: ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): You can explore how MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Have a look at the API reference for how to use MobileID --- ## App login ## Use case You are looking for a secure way for your end-users to log in to your mobile app, but without the need for username and passwords. You want to achieve this whilst still offering a positive and seamless user experience for your end-users. ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. Jane needs to log in to your mobile app so that she can access your online services. 1. To do this, Jane clicks on your app icon on the mobile device. 2. Your app opens and Jane authenticates herself using biometrics. :::note Success! Jane has now securely authenticated herself with two-factor authentication using your mobile app. ::: ## What it looks like The following diagram illustrates what an app login could look like with MobileID authentication, from the perspective of your end-user. Diagram showing end-user flow for app login ## Implementation :::tip Note This flow assumes that you are using ReuseID with MobileID authentication and that the end-user has an active ReuseID user and MobileID device. ::: The following flow is a suggestion on how to implement MobileID authentication for app login: 1. The end-user clicks on your app icon on their device. 2. The mobile app triggers a MobileID authentication request for the device. 6. The end-user authenticates using biometrics or a PIN. 7. MobileID verifies the authentication and sends a response to your server and app; confirming the authentication. 8. Your mobile app grants the end-user access to their account. Using MobileID authentication for app login is a straightforward and effective way to provide your end-users with a secure and seamless login experience. ### Sequence diagram ```mermaid sequenceDiagram title App login actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as ResuseID(MobileID) user->>app: End-user opens app app->>sp: Start authentication with userId and deviceId sp->>mobileid: POST /authentications with userId and deviceId mobileid-->>sp: OK sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result mobileid->>sp: POST /callback with authentication result sp-->>mobileid: OK note over user, app: End-user is now logged in to your app ``` ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): You can explore how app login with MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Have a look at the API reference for how to start an app login --- ## App transaction ## Use case You are looking for a secure way for your end-users to access or update information in your mobile app. You want to achieve this whilst still offering a positive and seamless user experience for your end-users. ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. Jane has forgotten her credit card PIN and is about to use your mobile app to view her PIN. 1. To do this, Jane opens and logs in to your mobile app. 2. Jane navigates to the place where she can view her credit card PIN in your mobile app. 3. Jane clicks on a button to view her credit card PIN. 4. Jane authenticates herself using biometrics. :::note Success! Jane has now securely authenticated herself with two-factor authentication and your app displays her credit card PIN. ::: ## What it looks like The following diagram illustrates what an app transaction could look like with MobileID, from the perspective of your end-user. Diagram showing end-user flow for app transaction ## Implementation :::tip Note This flow assumes that you are using ReuseID with MobileID authentication and that the end-user has an active ReuseID user and MobileID device. ::: The following flow is a suggestion on how to implement MobileID for app transactions for viewing a PIN: 1. The end-user navigates in your mobile app and clicks on view PIN. 2. The mobile app triggers a request to your backend for viewing their PIN. 3. Your server looks up the end-users PIN. 4. Your server triggers a MobileID authentication for the end-user; setting the PIN as the [post-operation context](/docs/mobile-identity/mobileid/features/operation-context.mdx#post-operation-context). 5. The end-user authenticates using biometrics or a PIN. 6. MobileID verifies the authentication and sends a response to your server and app; confirming the authentication. The response to your app contains the post-operation context with the PIN. 7. Your mobile app receives the PIN and displays it to the end-user. Using MobileID for app transactions is a straightforward and effective way to provide your end-users with a secure and seamless login experience. ### Sequence diagram ```mermaid sequenceDiagram title App transaction actor user as End-user participant app as Your app (with our SDK) participant sp as Your server participant mobileid as ReuseID>MobileID user->>app: End-user navigates to view PIN app->>sp: Start authentication with userId and deviceId sp->>sp: Find PIN sp->>mobileid: POST /authentications with userId, deviceId and PIN as post-operation context mobileid-->>sp: OK sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: End-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result with PIN as post-operation context mobileid->>sp: POST /callback with authentication result sp-->>mobileid: OK note over user, app: Your app now displays the PIN to the end-user ``` ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): You can explore how app login with MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Have a look at the API reference for how to start an app login --- ## Identity fraud prevention ## What is identity fraud? Identity fraud is when a fraudster gains access to an end-user's account. There are multiple ways in which a fraudster can gain access, such as through stolen credentials or phishing techniques. ## Use case You want to prevent identity fraud and provide your end-users with a secure way to onboard to new devices, whilst still offering an excellent user experience. Diagram showing onboarding fraud prevention ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. 1. An attacker downloads your app. 2. Jane gets a phone call from the attacker who pretends to be an employee at your company. They inform Jane that someone has gained access to her account. The attacker tells Jane that she needs to authenticate with an eID before they can help her stop this attack. 3. The attacker starts onboarding in your app with Jane's personal details. This triggers an eID authentication for Jane. 4. Jane authenticates with her eID, thinking it is to allow the bank to block the attacker. In reality, she is actually approving an onboarding to your app on the attacker's device. 5. The attacker sets up MobileID credentials with a PIN and biometrics. 6. The attacker is asked to perform a [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx), to confirm that it is Jane sitting in front of the device. 7. The authentication fails. :::note Fraud prevented! The attacker is blocked and cannot access Jane's account in your mobile app. ::: :::tip Why face authentication instead of Face ID? In some use cases, native biometrics such as Face ID will not work, and so server-side biometrics such as face authentication can be leveraged instead. You can read about the differences between Face ID and face authentication in our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx#what-is-the-difference-between-face-id-and-face-authentication) feature documentation. ::: ## What it looks like ### For the attacker The following diagram illustrates what it could look like to prevent fraud during onboarding with MobileID, from the perspective of the attacker. Diagram showing app flow for onboarding fraud prevention from attacker's perspective ### For your end-users The following diagram illustrates what it could look like to protect against fraud during onboarding with MobileID, from the perspective of your end-users. Diagram showing app flow for onboarding fraud prevention from end-user's perspective ## Implementation To protect against attackers getting access to your end-user's accounts, you can use our face authentication feature. This feature introduces an authentication method that uses server-side biometrics. For each authentication, it performs a two-second facial scan with **3D Liveness Check** and **3D Face Matching** on the server-side. This means you can perform face authentications across devices to verify that it is the correct end-user in front of the new device. :::info Want to learn more? To learn about our face authentication, how to implement it and how to test it, see our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/) feature documentation. ::: ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): You can explore how MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Have a look at the API reference for how to use MobileID --- ## Use cases(Use-cases) On this page, you can explore some examples of how and where MobileID is being used today. ## Examples MobileID is built flexibly, to enable you to implement any use case that you might have. You can use the buttons below to explore examples of how you can use MobileID: * [**Account recovery**](/docs/mobile-identity/mobileid/use-cases/account-recovery-face-authentication): Use our account recovery feature to avoid a full new onboarding for your end-users * [**App login**](/docs/mobile-identity/mobileid/use-cases/app-login): Use biometrics to log in to your mobile app * [**App transaction**](/docs/mobile-identity/mobileid/use-cases/app-transaction): Use biometrics to perform transactions in your mobile app * [**Identity fraud prevention**](/docs/mobile-identity/mobileid/use-cases/identity-fraud-prevention): Use our face authentication to prevent fraudsters from gaining access to accounts and prevent account takeovers * [**Reset authentication credentials**](/docs/mobile-identity/mobileid/use-cases/reset-authentication-credentials): Use our face authentication to avoid a full new onboarding for your end-users * [**Web login with username**](/docs/mobile-identity/mobileid/use-cases/web-login-username): Use your mobile app to log in to your website without the need for passwords * [**Web login with QR code**](/docs/mobile-identity/mobileid/use-cases/web-login-qr-code): Use your mobile app to log in to your website without the need for usernames or passwords {/* * [**PSD2-compliant payment authorisations**](): Documentation coming soon. Reach out to support for more details * [**Customer support identifications**](): Documentation coming soon. Reach out to support for more details * [**3DS payment authorisations**](): Documentation coming soon. Reach out to support for more details * [**Consent signatures**](): Documentation coming soon. Reach out to support for more details * [**Multiple users on the same device**](): Documentation coming soon. Reach out to support for more details */} ### Further use cases MobileID also supports: - PSD2-compliant payment authorisations - Customer support identifications - 3DS payment authorisations - Consent signatures - Multiple users on the same device ## Industries MobileID is a tool to drive mobile business. Today, there are millions of end-users who use this technology to perform authentications and authorisations across Europe. It can used in many different industries, such as: - Banking - Wealth management - Insurance - Healthcare - iGaming ### Customer cases You can read about how our customers are using our solutions today in our customer cases: * [**Banking**](https://www.signicat.com/customers/bank-norwegian): See how Bank Norwegian has created their own reusable identity * [**Banking**](https://www.signicat.com/customers/s-pankki): See how S-Pankki has increased customer engagement * [**Credit market**](https://www.signicat.com/customers/entercard): See how Entercard has achieved customer-driven, hassle-free SCA * [**Wealth management**](https://www.evli.com/en/news/try-the-new-my-evli-mobile): See how Evli has improved user experience and security * [**Banking**](https://www.signicat.com/customers/alisa-bank): See how Alisa Pankki is using Signicat as a single provider for authentication --- ## Reset authentication credentials ## Use case Your end-user ends up in a position where they have no active second-factor authentication method (neither PIN nor biometrics) on their device. This can happen if your end-user changes their biometrics on the device, and they have forgotten their PIN. In this situation, the end-user has a valid device, but no valid second-factor authentication method. When this happens, you want the process to reset the authentication credentials to: - Be secure. - Offer a positive and seamless user experience. - Avoid the additional cost of having your end-user go through a full onboarding again. :::tip Active second-factor authentication method If your end-user still has one active second-factor authentication method (either PIN or biometrics), then we recommend using this factor to reset the other second factor. You can read more about how to do this in the **Add or update** sections of our [Android](/docs/mobile-identity/encap/sdk-android/core-operations/#add-or-update) and [iOS](/docs/mobile-identity/encap/sdk-ios/core-operations/#add-or-update) SDK documentation. ::: ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. By mistake, Jane has reset her Face ID on her iOS device. 1. Jane opens you mobile app. Since Jane has reset her Face ID, she can no longer use Face ID to authenticate herself. The app falls back to asking Jane to authenticate with her PIN. 2. Jane has forgotten her PIN, and enters the wrong PIN three times. 3. Your app then informs Jane that she is locked out. To reset the authentication credentials, Jane has to perform a face authentication. 4. Jane starts by selecting a new PIN. 5. Jane completes a [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication.mdx). 6. Jane activates Face ID again. :::note Success! Jane has now securely reset her authentication credentials, and can now easily access your services again. ::: :::info Why face authentication instead of Face ID? In some use cases, native biometrics such as Face ID will not work, and so server-side biometrics such as face authentication can be leveraged instead. You can read about the differences between native and server-side biometrics in our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/#what-is-the-difference-between-face-id-and-face-authentication) feature documentation. ::: ## What it looks like The following diagram illustrates what it could look like to reset both the PIN and Face ID with MobileID, from the perspective of your end-user. Diagram showing end-user flow for resetting authentication credentials ## Implementation To reset your end-user's authentication credentials, you can use our face authentication feature. This feature introduces an authentication method that uses server-side biometrics. For each authentication, it performs a two-second facial scan with **3D Liveness Check** and **3D Face Matching** on the server-side. This allows you to perform face authentications when the PIN and native biometrics do not work. :::info Want to learn more? To learn about our face authentication, how to implement it and how to test it, see our [Face authentication](/docs/mobile-identity/mobileid/features/face-authentication/) feature documentation. ::: --- ## Web login with QR code ## Use case You are looking for a secure way for your end-users to log in to your website, but without the need for usernames and passwords. You want to achieve this whilst still offering a positive and seamless user experience for your end-users. ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. Jane needs to log in to your website so that she can access your online services. 1. To do this, Jane navigates to your website and arrives at the login page. 2. On this page, she sees the option to log in by scanning the displayed QR code with your mobile app. Jane opens your mobile app and scans the QR code. 3. Your app displays a message asking if she wants to log in to your website. 4. Jane approves the login request using biometrics or a PIN, and is now able to access your online services. :::note Success! Jane has now securely authenticated herself with two-factor authentication using your mobile app. ::: ## What it looks like The following diagram illustrates what a web login could look like with MobileID authentication, from the perspective of your end-user. Diagram showing end-user flow for web login with QR code ## Implementation :::tip Note This flow assumes that you are using ReuseID with MobileID authentication and that the end-user has an active ReuseID user and MobileID device. ::: There are many ways to implement MobileID authentication for web login with a QR code. The following flow is a suggestion: 1. The end-user visits your website and navigates to the login screen. 2. Your server starts a login session. 3. The website displays a QR code of the login session and asks the end-user to scan it. 4. The end-user opens your mobile app and scans the QR code. 5. Your mobile app will send a request to your server with the ID of the ReuseID user and the login session. 6. Your server connects the ReuseID user to the login session and starts a MobileID authentication. 7. The app displays a message asking the end-user to approve the login to your website. 8. The end-user approves the login using biometrics or a PIN. 9. MobileID verifies the authentication and sends a response to your server and app; confirming the authentication. 10. Your website grants the end-user access to their account. Using MobileID authentication for web login with a QR code is a straightforward and effective way to provide your end-users with a secure and seamless login experience. ### Sequence diagram ```mermaid sequenceDiagram title Web login with QR code actor user as End-user participant app as Your app (with our SDK) participant site as Your website participant sp as Your server participant mobileid as ResuseID(MobileID) user->>site: End-user opens login page site->>sp: Starts login sp->>sp: Create a login session sp->>site: Login session site->>site: Generate QR code, then display QR code to end-user user->>app: End-user opens app app->>site: Scan QR code site->>app: Login session app->>sp: Start authentication for login session and userId/deviceId sp->>sp: Find login session and link to userId/deviceId sp->>mobileid: POST /authentications with userId, deviceId and context for login session mobileid-->>sp: OK sp-->>app: OK app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: Display operation context, then end-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result mobileid->>sp: POST /callback with authentication result sp-->>mobileid: OK sp-->>site: Authentication result note over user, site: End-user is now logged in to your website ``` ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): Explore how web login with MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Explore endpoints and properties with example requests and responses --- ## Web login with username ## Use case You are looking for a secure way for your end-users to log in to your website, but without the need for passwords. You want to achieve this whilst still offering a positive and seamless user experience for your end-users. ## How it works Meet Jane, one of your active end-users who has activated MobileID in your mobile app. Jane needs to log in to your website so that she can access your online services. 1. To do this, Jane navigates to your website and arrives at the login page. 2. On this page, she sees the option to log in using your mobile app. Jane enters her username and clicks on the login button. 3. Within milliseconds, Jane receives a push notification on her mobile device. 4. When Jane clicks on the notification, your app opens up with a message asking if she wants to log in to your website. 5. Jane approves the login request using biometrics or a PIN, and is now able to access your online services. :::note Success! Jane has now securely authenticated herself with two-factor authentication using your mobile app. ::: ## What it looks like The following video illustrates what a web login could look like with MobileID, from the perspective of your end-user. ## Implementation :::tip Note This flow assumes that you are using ReuseID with MobileID authentication and that the end-user has an active ReuseID user and MobileID device. ::: There are many ways to implement MobileID authentication for web login. The following flow is a suggestion that involves using a username and MobileID for authentication: 1. The end-user visits your website and navigates to the login screen. 2. The website prompts the end-user to enter their username. 3. Once the end-user enters their username, the website triggers a MobileID authentication request for them. 4. The end-user then receives a push notification on their mobile device from your app, asking them to approve the login attempt. 5. The end-user opens the app, which displays a message asking them to approve the login to your website. 6. The end-user approves the login using biometrics or a PIN. 7. MobileID verifies the authentication and sends a response to your server and app; confirming the authentication. 8. Your website grants the end-user access to their account. Using MobileID authentication for web login is a straightforward and effective way to provide your end-users with a secure and seamless login experience. ### Sequence diagram ```mermaid sequenceDiagram title Web login with username actor user as End-user participant app as Your app (with our SDK) participant site as Your website participant sp as Your server participant mobileid as ResuseID(MobileID) user->>site: End-user enters username site->>sp: Start authentication with username sp->>sp: Find end-user'suserId and deviceId sp->>mobileid: POST /authentications with userId and deviceId mobileid-->>sp: OK mobileid-->>app: Send push notification user->>app: End-user opens app app->>mobileid: (SDK call) startAuthentication mobileid-->>app: startAuthentication response note over user, app: Display operation context, then end-user authenticates with biometrics or PIN app->>mobileid: (SDK call) finishAuthentication mobileid-->>app: Authentication result mobileid->>sp: POST /callback with authentication result sp-->>mobileid: OK sp-->>site: Authentication result note over user, site: End-user is now logged in to your website ``` ## Learn more * [**Try it out**](https://portal.encapsecurity.com/): Explore how web login with MobileID works in our demo portal * [**API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Explore endpoints and properties with example requests and responses --- ## API reference(Ongoing-monitoring) Ongoing Monitoring features different APIs to offer verification of customer data over time. * [**Person Monitoring API (Deprecated)**](/apis/person-monitoring/): Receive periodic updates of changes to an individual's identifying data * [**Ongoing Monitoring API**](/apis/ongoing-monitoring/): Receive periodic updates when an individual's or an organisation's identifying data changes --- ## Error codes for Ongoing Monitoring # Error codes When you make a request to the Signicat's Ongoing Monitoring API and there is an error, you will receive a response with an error message that contains an error code. If you encounter an error and require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. The table below shows how to interpret some of the error codes that you might encounter when using the API. :::tip Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: :::CustomTable{columnWidths="25% 75%"} | Error code | Description | |:-------------- |:------------- | | 0001 | Unauthorised. | | 0002 | Forbidden. | | 1100 | Requested a country that is not implemented. | | 1101 | Requested one or more sources that are currently unavailable. | | 1102 | Request targeted a resource where the requested dataset is not implemented. | | 1103 | Request targeted a resource where the profile is not implemented. | | 1104 | Requested a country that is not implemented by the provided data source. | | 1105 | Requested a profile that is not implemented by the provided data source. | | 1200 | The request targeted a country that does not exist. | | 1201 | Request targeted strict data sources without specifying anyone. | | 1202 | Request targeted one or more data sources that do not exist. | | 1203 | Request targeted a country that is not available. | | 1204 | Invalid request property combination. | | 1205 | Invalid expansion property. | | 1206 | Invalid query. | | 1207 | Invalid date of birth. | | 1208 | Bad request. | | 1209 | Unprocessable entity. | | 1210 | Invalid paging parameters. | | 1220 | Exceeded max iterations while searching for NACE section code, data source is corrupted. | | 1250 | Country not found. | | 1251 | Subdivisions not found. | | 1252 | Countries not found. | | 1300 | Internal communication error. | | 1301 | The source failed to respond within reasonable time. | | 1302 | Internal communication error. | | 1303 | Invalid argument. | | 1304 | Internal communication error. | | 1305 | The requested resource could not be found. | | 1306 | Internal communication error. | | 1307 | Internal communication error. | | 1308 | Source is temporarily exhausted. | | 1309 | Internal communication error. | | 1310 | Internal communication error. | | 1311 | Internal communication error. | | 1312 | Internal communication error. | | 1313 | Internal communication error. | | 1314 | Source is temporarily unavailable. | | 1315 | Internal communication error. | | 1316 | Internal communication error. | | 1500 | Something went wrong. Please contact us for assistance if the problem persists. | | 1601 | Multiple internal communication errors. | | 1700 | Could not find the specified cursor. | | 1701 | Invalid cursor. | ::: --- ## Ongoing Monitoring(Ongoing-monitoring) ## Introduction Signicat's Ongoing Monitoring service enables continuous tracking of entities (persons or organisations) for any changes in their demographic, financial or screening profiles. It ensures your system remains compliant with regulations by performing Enhanced Due Diligence (EDD) whenever a change is detected. Ongoing Monitoring allows you to automate monitoring, minimise regulatory risk and stay updated with the latest verified entity information from trusted data sources. ### Perpetual KYC Ongoing monitoring is also referred to as perpetual KYC, as it replaces periodic static data checks with continuous tracking of customer demographics, events, behaviors and risk profiles. This approach allows you to automatically trigger Enhanced Due Diligence (EDD) based on real-time events such as: - Address updates - Changes in industry or ownership - Sanctions matches - PEP status changes - Adverse media alerts By constantly updating risk profiles as changes occur, you can ensure that Customer Due Diligence (CDD) and EDD are performed exactly when needed, keeping your information accurate throughout the entire customer lifecycle. Perpetual KYC consists of five main steps: 1. Identifying entities 2. Implementing monitoring 3. Gathering insights 4. Performing Enhanced Due Diligence (EDD) 5. Protecting reputation This process of perpetual KYC is illustrated in the following diagram. Diagram of the ongoing monitoring process flow ### Why use Ongoing Monitoring? - Know Your Customer/Business (KYC/B) processes often rely on snapshots in time, which can quickly become obsolete. To address this, the AMLR 2027 framework requires continuous due diligence through ongoing monitoring. - Traditional KYC is calendar-driven (means performed at fixed time intervals, usually once a year), often leaving risk gaps and requiring heavy manual effort. Perpetual KYC is proactive, with real-time alerts, automated workflows and a focus on relevant changes for quicker threat detection. - One-time KYC/B) checks do not account for later changes to customer profiles, such as new sanctions or changes in ownership or financial status for both persons or organisations. Ongoing Monitoring solves this by continuously tracking customer profiles for specific changes. When an update is identified, it generates an alert, allowing you to maintain an accurate and compliant view of your customers. ## Features Key features of our Ongoing Monitoring product include: 1. **Automated data orchestration and daily checks**: Our system performs daily change checks against global registries and third-party providers. This eliminates the "snapshot" limitation of traditional KYC, making sure you stay up to date on ownership, legal status, roles, sanctions and financials without manual intervention. 2. **Intelligent delta detection and normalisation**: Using automated delta detection, the platform pinpoints discrepancies between historical and current data states. Regardless of the source's underlying format, our normalised schema mapping translates data into a single view, providing clarity across your entire entity ecosystem. 3. **Real-time event alerting**: By alerting on events, you receive notifications the moment a change is verified. Your downstream systems can listen to webhooks for these change detections, allowing for automated responses and seamless integration into your existing tech stack. 4. **Targeted EDD and risk mitigation**: By triggering Enhanced Due Diligence (EDD) at the right time, the system ensures resources are focused on actionable risk events. This helps reduce exposure to regulatory and reputational threats. 5. **Regulatory integrity and audit-ready logs**: Our Ongoing Monitoring solution keeps customer and partner data compliant with global regulations (AML, KYC, KYB). Every change, notification and subsequent action is captured in audit-ready logs, which provide a timestamped trail for regulatory reporting and internal governance. ## Use cases Here are some use case examples to better understand how you can use Ongoing Monitoring for both persons and organisations: ### For persons Individual profiles require sensitivity and precision. We monitor: - **Vital statistics**: Changes in name (marriage/legal change) or date of death notifications to prevent identity fraud. - **Locality**: Current residential address updates and changes in residency status. - **Risk and protection**: Changes in protected status (e.g., PEP designation, sanctions list additions or specific legal protections). ### For organisations Monitoring corporate structures is vital for uncovering hidden risks or "shell" shifts. We track: - **Identity and status**: Changes in legal name, legal status (e.g., active to insolvent) and industry/SIC codes. - **Ownership and control**: Shifts in Ultimate Beneficial Ownership (UBO), significant shareholding changes and board/role transitions. - **Risk indicators**: Updates to registered addresses and fluctuations in credit ratings that may signal financial instability or fraud risk. Sanction list additions can also be detected as a result of this change. ## Process flow The following steps outline the complete lifecycle of customer due diligence. The process begins when you onboard a new customer and perform the initial KYC/KYB checks. Based on the assessed risk level, the system then applies either standard or enhanced monitoring. From that point on, our service continuously tracks the customer's profile for any significant changes, triggering an alert for your team to investigate if a potential risk is detected. 1. **Profile creation**: The customer initiates a new monitoring profile. 2. **Entity addition**: Persons or organisations are added to the profile. 3. **Data distribution**: The system sends these entities to multiple data sources for updates. 4. **Data collection**: Data sources provide updated information on the entities (depending on the source). 5. **Change detection**: The system's change detection logic identifies changes in the collected data. 6. **Database update**: The database is updated with the new information. 7. **Events**: The system triggers events for the changes created. 8. **Latest snapshot**: The API retrieves the latest snapshot with an up-to-date view of the organisation's data. ## Guides * [**Integration guide**](/docs/ongoing-monitoring/integration-guide): Follow step-by step guides to integrate with our Ongoing Monitoring API * [**Test data**](/docs/ongoing-monitoring/test-data): Find out how to test specific cases or sources ## API reference * [**Person Monitoring API (Deprecated)**](/apis/person-monitoring/): Receive periodic updates of changes to an individual's identifying data * [**Ongoing Monitoring API**](/apis/ongoing-monitoring/): Receive periodic updates of changes to an individual's or organisations's identifying data ## Support * [**Release notes**](/docs/ongoing-monitoring/release-notes): View the release notes for Ongoing Monitoring * [**Error codes**](/docs/ongoing-monitoring/error-codes): View the error codes for Ongoing Monitoring If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Ongoing Monitoring integration guide ## Set up an API integration Setting up an API integration is the most flexible way of testing our Ongoing Monitoring solutions. You can use your preferred IDE, framework, Postman, etc. using credentials provided by Signicat. :::tip Before you start the integration Before you set up an API integration, we recommended that you familiarise yourself with the most common integration [use cases](/docs/ongoing-monitoring/#use-cases) and the [OpenAPI reference documentation](/apis/ongoing-monitoring/) to learn about available endpoints and their properties. You can also view our [Test data](/docs/ongoing-monitoring/test-data) guide, which contains test data for the data sources by attribute and country. ::: ## Using the API The most basic ongoing monitoring process will consist of the following steps: 1. [Prerequisites](#1-prerequisites). 2. [Create a monitor](#2-create-a-monitor). 3. [Add an organisation](#3-add-an-organisation). 4. [Send organisations to data sources](#4-send-organisations-to-data-sources). 5. [Get changes](#5-get-changes). 6. [Get the latest snapshot, if needed](#6-get-the-latest-snapshot-if-needed). ### 1. Prerequisites Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). ### 2. Create a monitor Create a Monitor by making an HTTP POST request to the [Create monitor endpoint](pathname:///apis/ongoing-monitoring/#tag/Monitor-Endpoints/operation/CreateMonitor). ### 3. Add an organisation Add an organisation to the Monitor by making an HTTP POST request to the [Add organisation endpoint](pathname:///apis/ongoing-monitoring/#tag/Organisation-Endpoints/operation/AddOrganization). ### 4. Send organisations to data sources The system automatically distributes the organisation to the data sources configured for the monitor. ### 5. Get changes Get changes, if detected, by making an HTTP GET request to the one of the [Changes endpoints](pathname:///apis/ongoing-monitoring/#tag/Changes-Endpoints). You can retrieve changes by `monitorId` alone or by `monitorId` and `changeId`. The endpoints return paginated lists of detected changes. #### Response example ``` json { "size": 3, "nextCursor": 2, "limit": 1000, "items": [ { "id": 1, "referenceKey": "402d1ce2-ce71-4f9b-b252-3fa90fef0de4", "monitorId": "8a1d17e9-626d-44b0-9eaa-0935bf2c8fe1", "detected": "2025-09-11T11:27:11.3183971Z", "created": "2025-09-10T17:27:11.3183975Z", "changes": [ { "profile": "screening", "attribute": "CompanyName", "action": "Update", "new": "New Name", "old": "Previous Name" }, { "profile": "screening", "attribute": "MatchStrength", "action": "Update", "new": "100", "old": "60" } ] } ] } ``` ### 6. Get the latest snapshot, if needed Get the latest snapshot, if needed, by making an HTTP GET request to the [Get latest organisation snapshot endpoint](pathname:///apis/ongoing-monitoring/#tag/Organisation-Endpoints/operation/GetLatestOrganizationSnapshot). The endpoint returns the most recent full snapshot of the organisation's data. #### Response example ``` json { "country": "NOR", "name": "Organisation Name", "added": "2025-10-15T08:19:58.9412252Z", "lastUpdate": "2025-10-16T08:19:58.9412266Z", "organisationNumber": "12345678", "operationalStatus": "Active", "externalId": "1454-15", "alias": "Organisation Alias", "legalForm": "Other", "vatNumber": "12345678", "email": "example@example.pt", "registrationDate": "2025-10-15T08:19:58.9412273Z", "phone": { "number": "12345678", "region": "NOR" }, "addresses": [ { "type": "Registered", "startDate": "2025-10-15T08:19:58.9412297Z", "endDate": "2025-10-17T08:19:58.9412295Z", "country": "NOR", "postCode": "postcode", "postPlace": "postplace", "street": "Street" } ], "industries": [ { "naceCode": "1234" } ], "names": [ { "name": "Organisation Name", "type": "Business", "startDate": "2025-10-15T08:19:58.9412319Z", "endDate": "2025-10-17T08:19:58.9412318Z" }, { "name": "Organisation Name", "type": "Registered", "startDate": "2025-10-15T08:19:58.9412323Z", "endDate": "2025-10-17T08:19:58.9412323Z" } ], "screening": { "matchStrength": 100, "listType": "SANCTION", "source": "EU_GLOBAL" }, "finance": { "creditRating": { "description": "description", "score": "10", "scoringSystem": "System", "url": "example.com", "year": 2025 }, "financials": [ { "currency": "EUR", "grossProfit": 12, "netProfit": 13, "netProfitAfterTax": 18, "turnover": 1, "year": 2024 }, { "currency": "EUR", "grossProfit": 30.02, "netProfit": 31.902, "netProfitAfterTax": 32.98, "turnover": 2, "year": 2023 } ], "paymentRemarkInfo": { "numberOfRemarks": 1 } }, "roles": { "companies": [ { "name": "Company", "roles": [ { "roleCategory": "Auditor", "description": "description", "startDate": "2025-10-15T08:19:58.9412391Z", "endDate": "2025-10-17T08:19:58.9412389Z" } ], "organisationNumber": "12345678" } ], "persons": [ { "address": { "country": "NOR", "postCode": "postcode", "postPlace": "postplace", "street": "Street" }, "dateOfBirth": "1985-10-16", "idNumber": { "country": "NOR", "number": "12345", "type": "National" }, "name": { "first": "first", "middle": "middle", "last": "last", "full": "first middle last", "status": "All" }, "nationality": "NOR", "roles": [ { "roleCategory": "Ceo", "description": "description", "startDate": "2025-10-15T08:19:58.9412415Z", "endDate": "2025-10-17T08:19:58.9412415Z" } ] } ], "others": [ { "id": "123", "name": "other", "roles": [ { "roleCategory": "Auditor", "description": "description", "startDate": "2025-10-15T08:19:58.9412402Z", "endDate": "2025-10-17T08:19:58.9412401Z" } ] } ] } } ``` ## API reference Explore our Ongoing Monitoring reference documentation to look up all API endpoints and properties as well as view sample requests and responses. * [**Ongoing Monitoring API**](/apis/ongoing-monitoring/): Receive periodic updates of changes to an individual's or organisations's identifying data --- ## Release notes for Signicat Ongoing Monitoring API # Ongoing Monitoring release notes ## 18.04.2025 ### New Organisation Monitoring API We released the initial version of the Signicat **Ongoing Monitoring** for **Organisations**, a solution designed for monitoring changes to organisations across multiple registries. :::note Organisation Monitoring API specifications **Base URL**: `https://api.signicat.com/info/monitor/` **Supported properties**: - Data sources: `trapets` - Entity types: `Organisation` - Profiles: `screening` ::: This initial release provides core functionalities to use the API. Additional features will be introduced periodically based on product roadmap and customer feedback. #### Key Features Here is an overview of the features in the initial release: - **Monitor management**: Endpoints for creating and retrieving monitors. - **Organisation monitoring**: Endpoints for adding and querying monitored organisations. - **Change tracking**: Endpoints for retrieving historical changes at both the organisation and monitor levels. - **Data models**: Standardised request and response objects for all endpoints. Learn more about the API features in the sections below. #### Monitor management **Creating monitors** At the core of Ongoing Monitoring is the monitor object, the main resource where you define properties that shape how the monitor will track changes to the data of organisations over time. When creating a new monitor, you define parameters to control the following properties: :::CustomTable | Property | Parameter | Description | Supported values (v1) | Required | |:------------|:----------|:------------|:---------|:---------| | Name | `name` | Human-readable short label. | Any. String. | Yes | | Description | `description` | An optional description. | Any. String. | No | | Entity type | `entityType` | The type of customer data to monitor: `person` or `organisation`. | `organisation` | Yes | | Data source | `sources` | The national and commercial data providers, and provider-configuration, to use in the monitor. For example, a company register. | `trapets` | Yes | | Profile | `profiles` | The categories of information to monitor. For example, UBO or Basic. This specifies the minimum data profile requirements for each entity within a monitor. | `screening` | Yes | ::: Example of request body to the `Create monitor` endpoint: ```http POST /info/monitor HTTP/1.1 Host: api.signicat.com Content-Type: application/json Authorization: Bearer Content-Length: 228 { "name": "MyMonitor", "description": "Example of a Monitor with Trapets", "entityType": "Organisation", "sources": [ { "name": "trapets" } ], "profiles": [ "screening" ] } ``` :::note Authorization Token To connect to the Organisation Monitoring API, you must obtain API credentials that you exchange for an authorization token. Learn more in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::warning Permissions required To grant your API client the appropriate permissions to access the initial release environment, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::info Monitor ID A monitor has a unique ID. When you create a new monitor object, you receive the monitor ID in the response. ::: **Retrieving monitors** After creating a new monitor object, you can fetch the monitor details using the unique `monitorId` that you received in the initial response. To do this, you pass the `monitorId` in the URL to the `Get monitor` endpoint. For example, let's assume the monitor ID is `01966198-6a9a-76b1-914f-5990e29f0de4`. Request example: ```http GET /info/monitor/01966198-6a9a-76b1-914f-5990e29f0de4 HTTP/1.1 Host: api.signicat.com Accept: application/json Authorization: Bearer ``` Response example: ```json { "id": "01966198-6a9a-76b1-914f-5990e29f0de4", "accountId": "", "name": "MyMonitor", "sources": [ { "name": "trapets" } ], "profiles": [ "screening" ], "description": "Example of a Monitor with Trapets", "size": 0, "entityType": "Organisation", "createdAt": "2025-04-18T07:41:40.882576Z", "isEnabled": true } ``` Next to the defining properties of the monitor, the response contains the following additional fields: - `id`: The unique identifier of the monitor object. - `accountId`: The identifier of your account in the Signicat Dashboard. - `size`: The number of entities (organisations or persons) linked to the monitor. For example, the number of organisations to monitor. - `createdAt`: Creation timestamp of the monitor object. - `isEnabled`: A boolean field to indicate if the monitor is active. #### Organisation monitoring To start tracking changes to an organisation, you must add an organisation object, as an entity, to an existing monitor by sending a `POST` request to the `Add organisation` endpoint. You define the monitor ID in the URL `/info/monitor/{{monitorId}}/organisations`. Request example: ```http POST /info/monitor/{{MONITOR_ID}}/organisations HTTP/1.1 Host: api.signicat.com Content-Type: application/json Authorization: Bearer Content-Length: 186 [ { "organisationNumber": "23432342", "source": "trapets", "country": "NOR", "companyName": "Signicat", "referenceKey": "402d1ce2-ce71-4f9b-b252-3fa90fef0de4" } ] ``` In the body of the request, you must define the following required parameters: - `organisationNumber`: The company registration number. - `source`: The data source to use when tracking changes to the organisation. - `country`: Country code (ISO 3166-1 alpha-3). - `companyName`: The name of the organisation to monitor. - `referenceKey`: A time-sortable UUIDv7 string to uniquely identify the entity object. UUIDv7 offers a precise timestamp that you can use to filter changes. :::warning Important The `referenceKey` you supply must conform to the [UUIDv7](https://uuid7.com/) standard. Example: `01966292-9629-74cf-b2af-513bd9ac6fe9`. ::: **Retrieving latest organisation data** You can fetch the most recent snapshot of an organisation data by using `monitorId` and `referenceKey`. Request example: ```http GET /info/monitor/{{MONITOR_ID}}/organisations/{{REFERENCE_KEY}} HTTP/1.1 Host: api.signicat.com Accept: application/json Authorization: Bearer ``` Response example: ```json { "country": "NOR", "name": "Organisation Name", "added": "2025-04-18T11:39:44.5169694Z", "lastUpdate": "2025-04-19T11:39:44.5169712Z", "organisationNumber": "12345678", "operationalStatus": null, "externalId": "1454-15", "alias": "Organisation Alias", "legalForm": "Other", "screening": { "matchStrength": 100, "listType": "SANCTION", "source": "EU_GLOBAL" } } ``` The shape of the response varies depending on the profile you choose. For an overview of the properties, see the `Get organisation` endpoint. #### Tracking changes A change refers to an observed change to a set of attributes of a monitored entity. You can retrieve information about changes related to an individual entity within a monitor, or across all the entities for a given monitor. **Retrieve changes per organisation** Retrieves all modifications for a given organisation (using `monitorId` and `referenceKey`). The endpoint returns information about the changed attributes, type of change and an overview of previous and new values. **Retrieve changes per monitor** Retrieves all changes across organisations in a monitor (using `monitorId`). --- To learn more about upcoming releases, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Test data for Ongoing Monitoring # Test data This page contains information about the test data available for the data sources supported by Signicat's Ongoing Monitoring. You can find test data for data sources used for each attribute and country. An attribute corresponds to an endpoint of the Ongoing Monitoring API. ## Index Use the links on the "Source" column to learn more about the test data available for each information source. :::CustomTable{columnWidths="33% 33% 33%"} | Attribute | Country | Source | | ------------ | ------- | ------------------------------------------------------------------------------------------------- | | Address | Norway | [Det sentrale folkeregister (via Infotorg)](#norge-folkeregisteret) | | Address | Sweden | [Statens personadressregister (SPAR)](#statens-personadressregister-spar) | ::: ## Sources ### Norge Folkeregisteret There are two ways to access Norge Folkeregisteret (Norway National Registry): - **Infotorg**: Provides test data on demand. Learn more on the Infotorg [website](https://www.infotorg.no/tjenester/folkeregisteret) (in Norwegian). - **Skatteetaten**: The Norwegian agency responsible for resident registration and tax collection. The test data is available [on Skatteetaten's documentation site](https://skatteetaten.github.io/folkeregisteret-api-dokumentasjon/test-for-konsumenter/) (in Norwegian). - You can search for synthetic test data with [Tenor test data search](https://www.skatteetaten.no/skjema/testdata/) — an online solution offered by Skatteetaten. ### Statens personadressregister (SPAR) For the Ongoing Monitoring API, use the test data in [this file](https://www.statenspersonadressregister.se/media/hhhjhtyf/spar-bruttodata-xml.zip). --- ## Best practices(Passkeys) This page contains useful information about best practices and considerations for anyone involved in implementing Passkeys, for example developers, project managers and technical architects. The scope is for select topics that can assist you during your integration, such as key decisions, tips and ways to avoid common issues. ## Handling redirects and Content Security Policy (CSP) When a passkey registration or authentication finishes, the end-user's browser carries out the final redirect to your provided `rpRedirectUri`. As this is a client-side action, you must account for browser security policies and verify that the operation was successfully completed. :::warning Important The end-user is redirected to the landing page in the `rpRedirectUri` regardless of the outcome of the registration or authentication operation.

That is why this page must never grant access or assume success without verifying that the operation was successfully completed. ::: If your `rpRedirectUri` redirects to another host or domain, the browser's Content Security Policy (CSP) will block it, whereas redirecting to another page on the same server usually works. ```text title="Example: Redirect blocked by CSP" From: https://www.mydomain.com To: https://mydomain.com ``` ```https title="Example: Redirect not blocked by CSP" From: https://www.mydomain.com/first-page To: https://www.mydomain.com/second-page ``` If the browser's CSP blocks the redirect, the end-user may see an error page or appear stuck. However, the underlying passkey operation has already completed on the backend. As this is a browser-side redirect failure, it does not appear in the Signicat audit logs or API responses. :::tip Our recommendation As you cannot see browser-side redirect failures in the Signicat audit logs or API responses, we recommend that you test your redirect flow end-to-end before deploying to production. ::: ## Clearing browser cookies If the end-user's browser becomes unresponsive or appears stuck during a passkeys operation, then we recommend that you ask the end-user to clear their browser cookies and to try again. As this is a browser-side issue, no error message is generated, and it does not appear in the Signicat audit logs or API responses. ## Choose events (callback) or polling Events are our way of letting you know when something happens in one of our services. When an asynchronous operation completes, or when ReuseID gets a notification that a device has changed state, ReuseID publishes an event with the operation result. You can use the Signicat events service to subscribe to events, so that you automatically receive the result at your specified notification URI. This is often referred to as callback. You can also get the operation result back through polling. The result that you receive through the Signicat events service is the same as the result obtained by polling, but wrapped in a Signicat event object. For production, we always recommend that you use the Signicat events service instead of polling. This offers the best usability and responsiveness, as it has the least amount of latency. It also means that you do not need to conduct additional polling calls. :::note Want to learn more? - For information generic to all Signicat events, see the general [Events](/docs/dashboard/settings/events.mdx) documentation. - For information specific to Passkeys, see the [Passkeys](/docs/reuseid/events/#passkeys) section in the ReuseID **Events** documentation. ::: ## Segments When conducting certain operations on the **User** resource, it is possible to pass an optional parameter called `segment` in the request. The following operations support this parameter: - [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) - [**Update user**](pathname:///apis/reuseid/#tag/User/operation/updateUser) As the `segment` is then returned in the response of a respective transaction, it allows you to group the end-users and corresponding transactions based on a segmentation of your choice. For example, if your app is used by end-users across multiple countries, you could use segments to get statistics for app usage per country, In this example, you could segment your end-users using country codes such as `NO`, `SE`, `DK`. ## Resolve an external reference When a user is created with the [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) operation, we generate a valid UUID to identify it called a `userId`. This is required for carrying out most operations such as registration and authentication. You may already have your own internal customer references that you store and use for your customers. In the context of this product, we refer to it as an external reference. If you do not want to store the Signicat-generated `userId`, then you can use the [**Resolve external reference**](pathname:///apis/reuseid/#tag/User/operation/resolveUserIDByExtref) operation to supply the associated `externalRef` and fetch the `userId`. Once fetched, the `userId` can then be can then be used to start the subsequent operation as normal. --- ## How it works(Passkeys) A passkey is made up of two keys: - **Private key**: This is securely stored with the end-user. - **Public key**: This shared and stored server side (Signicat). The key pair is created by the end-user's key provider used in their browser. Some examples of key providers are: - Apple - Google - Microsoft - A password manager, for example 1Password - FIDO2 hardware tokens, for example YubiKeys Once the passkey key pair has been created by the key provider, the private key is safely stored in the end-user's key provider ecosystem. As it is managed by the key provider ecosystem, the passkey syncs securely across all of the end-user's devices. This means that your end-users can log in from their mobile phone, tablet, or laptop with ease. :::info What does this mean? A key provider ecosystem for passkeys refers to entities responsible for creating, managing, storing and synchronising passkeys across devices. Examples of these entities include Apple iCloud Keychain and Google Password Manager. ::: ## What makes passkeys secure? The Signicat passkeys service is built on three powerful technologies: - **FIDO2**: An open security standard supported by Google, Apple, Microsoft, and others. - **WebAuthn**: A W3C standard that lets browsers use secure keys instead of passwords. - **Signicat**: A European leader in digital identity services; offering reusable digital identities and combining authentication with identity proofing. ## Technical flow Passkey authentication is based on the WebAuthn standard, which is part of the FIDO2 protocol suite. It uses public key cryptography with a challenge-response mechanism, where the end-user signs a one-time challenge (a nonce) using their private key after biometric verification. For a high-level explanation of how a passkey authentication works, see the steps below: 1. The end-user navigates to a website in their browser, then clicks **Log in with passkey**. 2. They are redirected to the Signicat login page. Here, they click **Authenticate**. 3. Signicat sends a challenge (a nonce) to the end-user's browser. The end-user does not see the challenge. 4. The end-user authenticates with biometrics on their device, to unlock the private key that signs the challenge. 5. The browser sends the signed challenge to Signicat. 6. Signicat verifies the signed challenge with the public key, then redirects the end-user back to the website with the result of the login. ## End-user flow For an example of what the user interface can look like, see the image slider below: :::details Click to view steps 1. The end-user navigates to a website in their browser, then clicks **Log in with passkey**. 2. They are redirected to the Signicat login page. Here, they click **Authenticate**. 3. Automatically, an overlay is shown from their key provider which asks the end-user if they want to log in. 4. The end-user authenticates with biometrics on their device. 5. Once authenticated successfully, the end-user is logged in. ::: ## Get started In our quick start guide, you can learn how to use a tool of your choice to make API requests and test out ReuseID with Passkeys authentication: * [**ReuseID authentication using Passkeys**](/docs/passkeys/quick-start-guides/passkeys-authentication): Learn how to do a ReuseID authentication using Passkeys with our APIs --- ## Passkeys(Passkeys) Signicat Passkeys lets you authenticate authorise end-users securely within a browser. It offers a phishing-resistant, cross-platform login experience using device biometrics, which is perfect for web flows. With passkeys, you can provide a modern and passwordless experience that reduces fraud, reduces drop-off and boosts conversions. :::tip Our recommendation We recommend that you use this authentication method if you interact primarily with your end-users in a browser and are looking to replace traditional passwords. ::: ## About Passkeys - It offers a phishing-resistant way to authenticate your end-users, using built-in biometrics such as fingerprint or facial recognition. - It offers a seamless login experience without the need for usernames, passwords or one-time codes. - It can improve security and usability when your end-users access your services in a browser. - It can simplify login flows and eliminate password-related risks. - It works across devices and platforms. - It works the same way across all countries, making them ideal for businesses operating in multiple markets. ## Get started * [**Quick start guide**](/docs/passkeys/quick-start-guides/): Learn how to do a Passkeys authentication using the ReuseID API * [**How it works**](/docs/passkeys/how-it-works): Learn about how Passkeys works ## Support * [**Error codes**](/docs/reuseid/error-codes/#passkeys-error-codes): View the error codes for Passkeys * [**Best practices**](/docs/passkeys/best-practices/): Learn about best practices when implementing Passkeys --- ## Quick start guides(3) Our quick start guides show you how to test out Passkeys authentication and more with API requests and a tool of your choice. * [**Authentication using Passkeys**](/docs/passkeys/quick-start-guides/passkeys-authentication): Learn how to do a Passkeys authentication using the ReuseID API --- ## Quick start guide(5) # Quick start guide Learn how to test out ReuseID with Passkeys authentication using the ReuseID API. This quick start guide shows you how to: 1. Get set up for testing Passkeys. 2. Create a ReuseID user 3. Register a passkey. 4. Perform an authentication. :::info Want to try Passkeys without making API requests? This guide requires that you make API requests using a tool of your choice. If you want to try out Passkeys without making API requests, then you can use our [passkey demo](https://passkey-demo.sandbox.signicat.com/mint/2cdc2c93cf1440d986e80528d9dc5b41). Here, you can register and authenticate with a passkey. ::: ## Prerequisites ### 1. Connect to the ReuseID API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set permission **ReuseID Passkey API** for your API client: ::: ### 2. Create a domain As passkeys are registered to a specific domain, you need to have a domain registered for your account. - If you already have a domain, then you can skip this step. - If you do not have a domain, then you need to create one from the [Organisation management](https://dashboard.signicat.com/org-mgmt/) page in the Signicat Dashboard. :::info Want to learn more? To learn how to create a domain in the Signicat Dashboard, see our documentation: - Create a [Signicat Standard domain](/docs/dashboard/organisation-management/domains/standard.mdx). - Create a [Custom domain](/docs/dashboard/organisation-management/domains/custom/). ::: ### 3. Onboard your account to Passkeys You need to add passkeys to your account using the Signicat Passkeys service. To do this: 1. Go to **Signicat Dashboard** > **Products** > [**Passkeys**](https://dashboard.signicat.com/passkeys/). 2. Click the **Add Passkeys** button. 3. Click the **+ Add Passkeys to the account** button. ### 4. Set up ReuseID in Postman :::note Using other tools This guide provides steps for using [Postman](https://www.postman.com/downloads) as a tool for initiating the APIs, however, you can use the preferred tool of your choice. ::: To set up ReuseID in Postman and obtain an access token: 1. Open Postman. 2. Import the collection. To do this: 1. Navigate to the **Collections** tab on the left-hand side of the screen, then click the **Import** button. Screenshot showing import of the collection into Postman 2. In the blank field in the dialogue box, paste the URL to our ReuseID API specification `https://api.signicat.com/reuseid/core/openapi.json`. :::tip Our recommendation We recommend that you generate the request and response parameters from the examples in the schema, and that you create folders according to the tags. To do this: 1. Click the **View import settings** button. 2. In the **Parameter generation** section, select **Example** from the dropdown menu. 3. In the **Folder organization** section, select **Tags** from the dropdown menu. ::: 3. Click the **Import** button in the dialogue box to finalise the import. 3. Create variables. To do this, click the **Variables** tab, and add the following: :::CustomTable{columnWidths="25% 75%"} | Variable | Value | | :-- | :-- | | `baseUrl` | This variable becomes present after import.

Make sure that the value is `https://api.signicat.com/reuseid/core`. | | `authClientID` | The client ID that you obtained when you created the API client. | | `authClientSecret` | The client secret that you obtained when you created the API client. | ::: Screenshot showing creation of variables in Postman 4. Set up authorisation. To do this, go to the **Authorization** tab and update the following: :::CustomTable{columnWidths="25% 75%"} | Name | Value | | :-- | :-- | | Type | `OAuth 2.0` | | Grant type | `Client Credentials` | | Access Token URL | `https://api.signicat.com/auth/open/connect/token` | | Client ID | `{{authClientID}}` | | Client Secret | `{{authClientSecret}}` | | Scope | `signicat-api` | ::: Screenshot showing set up of authorisation in Postman 5. Click on the **Get new access token** button to get an access token. 6. To add the token to the requests, click **Proceed**, then **Use Token**. 7. Save your changes. :::tip Auto-refresh your access token To automatically refresh your access token after it has expired, enable the **Auto-refresh token** toggle button under the **Authorization** tab. You can only enable auto-refresh tokens after you have received your first valid token. ::: :::note Success! You have now set up Postman for the ReuseID API. ::: ## Try ReuseID with Passkeys authentication You have now completed all required preparations and are ready to perform ReuseID operations. ### 1. Create a ReuseID user To create a ReuseID user: 1. In Postman, navigate to **Signicat ReuseID API reference** > **User** > **Create user**. 2. Under the **Body** tab, you can input your own request body. ```json title="Example: Request to create a ReuseID user" { "attributes": { "first-name": "Jane", "last-name": "Smith", "passkeys-name": "Jane Smith", "passkeys-displayname": "Jane Smith" } } ``` ::::details What does this example mean? In this example, we added user attributes for the passkey name and passkey display name: - `passkeys-name` - `passkeys-displayname` This is because we attempt to retrieve those attributes from the ReuseID user in the **Passkey registration** operation shown in the next step.If they do exist, then they are used as the `name` and `displayName` respectively when creating the passkey. Depending on the passkey provider that the ReuseID user is using, these may be displayed in the overlays to help identify the passkey during registration and authentication operations.If they do not exist, then the `userId` supplied in the request is used instead when creating the passkey. :::note Note You can also add these user attributes to a ReuseID user at a later point using the [Update user](/apis/reuseid/#tag/User/operation/updateUser) endpoint. ::: :::: 3. Click the **Send** button. ```json title="Example: Response from creating a ReuseID user" { "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981", "created": "2023-08-16T11:25:50.923Z", "state": "ACTIVE", "attributes": { "first-name": "Jane", "last-name": "Smith", "passkeys-name": "Jane Smith", "passkeys-displayname": "Jane Smith" } } ``` :::note Success! You have now created a ReuseID user. ::: :::tip Our recommendation We recommend that you save the `id` of your ReuseID user (user ID), as it is needed in future operations. ::: ### 2. Register a passkey Now that you have created a ReuseID user, you can register a passkey. To do this: 1. In Postman, navigate to **Signicat ReuseID API reference** > **Passkey Registration** > **Start passkey registration**. 2. Under the **Body** tab, you can input your own request body. For this API, it is required to set the user ID (`userId`). This is the ID of the ReuseID user that you created in the previous section. ```json title="Example: Request to register a Ppasskey" { "userId": "76bfe9e6-1fe2-4b92-b742-a66015a98981" } ``` :::note Redirect URL In this guide we do not provide a redirect URL. When a redirect URL is not provided, our default page is used and you are redirected to a page with details about the transaction. ::: 3. Click the **Send** button. 4. You have now started a registration operation. The response contains an `idpRedirectUri`, which you need in the next step. ```json title="Example: Response from registering a passkey" { "transactionId": "b75d275e-e334-481d-b362-6e4fde7c321c", "accountId": "a-spge-vFwveHnQyN8J0XSI10wv", "state": "PENDING", "created": "2025-10-17T19:14:32.297Z", "passkey": { "domain": "quick-start.sandbox.signicat.com" }, "user": { "id": "89c52851-213b-4092-9ed7-a7c607f41a74" }, "idpRedirectUri": "https://quick-start.sandbox.signicat.com/passkeys/web/registrations/start?transactionId=b0d70ca7-62ba-4d59-b1a7-b695d82dcf14&messageId=8edf3dd6-326f-4cd7-a6a7-e53d3f21c96c", "operationProperties": { "sessionTimeout": 300000, "sessionExpiryTime": "2025-10-17T19:19:32.259Z", "userVerification": "preferred" } } ``` 5. Copy the `idpRedirectUri` from the response and open it in your preferred browser. 6. Follow the instructions in the browser to register a passkey. 7. Once the registration is complete, you are redirected to our default page containing details about the passkey (or the `redirectUrl` you provided in the request). 8. To get the full response, open Postman, navigate to **Passkeys registration** > **Get state of ongoing registration**. 9. Under the **Params** tab, update the value of `transactionId` to the value you obtained in the **Start registration** response. 10. Click the **Send** button. ```json title="Example: Response from fetching the state of a Passkeys registration" { "transactionId": "749edf33-434b-420f-9b8b-2a49b77c815c", "accountId": "a-spge-vFwveHnQyN8J0XSI10wv", "state": "COMPLETED", "created": "2025-10-17T19:04:43.453Z", "completed": "2025-10-17T19:05:05.740Z", "passkey": { "id": "a5ffb695-9800-4cac-a470-8b5f906f7dfa", "domain": "quick-start.sandbox.signicat.com", "created": "2025-10-17T19:05:05.731Z", "aaGuid": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd", "userVerificationRequested": true, "userPresenceRequested": true }, "user": { "id": "89c52851-213b-4092-9ed7-a7c607f41a74" }, "idpRedirectUri": "https://quick-start.sandbox.signicat.com/passkeys/web/registrations/start?transactionId=e008e5cd-364b-475e-b33b-2978a4d1bc19&messageId=60c8be31-ee5a-411f-84dc-b9d7615b3258", "operationProperties": { "sessionTimeout": 300000, "sessionExpiryTime": "2025-10-17T19:09:43.409Z", "userVerification": "preferred", "userVerificationRequired": true, "userPresenceRequired": true }, "riskAttributes": { "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36" } } ``` :::note Success! You have now registered and activated a passkey. ::: :::tip Our recommendation We recommend that you save the `id` of your passkey, as it is needed in future operations. ::: ### 3. Authenticate with Passkeys Now that you have registered a passkey, you can authenticate with that passkey. To do this: 1. In Postman, navigate to **Signicat ReuseID API reference** > **Passkey authentications** > **Start authentication**. 2. Under the **Body** tab, you can input your own request body. For this API, nothing is required. ```json title="Example: Request to authenticate" { } ``` 3. Click the **Send** button. 4. You have now started a authentication operation. The response contains an `idpRedirectUri`, which you need in the next step. ```json title="Example: Response from the authentication" { "transactionId": "5ad732c2-699a-41c9-9a83-6131ecb43eea", "accountId": "a-spge-vFwveHnQyN8J0XSI10wv", "state": "PENDING", "created": "2025-10-17T19:41:52.686Z", "idpRedirectUri": "https://quick-start.sandbox.signicat.com/passkeys/web/authentications/start?transactionId=e6edbc42-8328-4490-b239-4def72fddde3&messageId=efc20a4b-93ee-4da7-8faf-caaa0afa2b7e", "operationProperties": { "sessionTimeout": 300000, "sessionExpiryTime": "2025-10-17T19:46:52.653Z", "userVerification": "preferred", "domain": "quick-start.sandbox.signicat.com" } } ``` :::note Redirect URL In this guide we do not provide a redirect URL, when a redirect URL is not provided you will use our default page and get redirected to a page with details about the transaction. ::: 5. Copy the idpRedirectUri` and open it in your preferred browser. 6. Follow the instructions in the browser to register a passkey. 7. Once the authentication is done you will be redirected to our default page containing details about the passkey (or the `redirectUrl` you provided in the request). 7. To get full response, in Postman, navigate to **Signicat ReuseID API reference** > **Passkey authentications** > **Get state of ongoing authentication**. 8. Under the **Params** tab, update the value of `transactionId` to the value that you obtained in the **Start authentication** response. 9. Click the **Send** button. ```json title="Example: Response from fetching the state of an authentication" { "transactionId": "cb669c56-ac19-4a9e-a487-2151a3df5f4e", "accountId": "a-spge-vFwveHnQyN8J0XSI10wv", "state": "COMPLETED", "created": "2025-10-17T19:48:27.450Z", "completed": "2025-10-17T19:49:02.056Z", "passkey": { "id": "a5ffb695-9800-4cac-a470-8b5f906f7dfa" }, "user": { "id": "89c52851-213b-4092-9ed7-a7c607f41a74" }, "idpRedirectUri": "https://quick-start.sandbox.signicat.com/passkeys/web/authentications/start?transactionId=bbe7ae12-b056-49ff-a1a3-709264352f29&messageId=ad28f221-1b29-4afd-bc5b-d47c9bf42754", "operationProperties": { "sessionTimeout": 300000, "sessionExpiryTime": "2025-10-17T19:53:27.411Z", "userVerification": "preferred", "userVerificationRequired": true, "userPresenceRequired": true, "domain": "quick-start.sandbox.signicat.com" }, "riskAttributes": { "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36" } } ``` :::note Success! You have now completed a passkey authentication. ::: ## Learn more You can explore our developer documentation to learn more about what you can do with ReuseID and passkeys, and further test out the product. * [**How it works**](/docs/reuseid/how-it-works/): Learn about the operations that make up the integration process * [**API reference**](/docs/reuseid/api-reference/): Look up all API endpoints and properties. View sample requests and responses --- ## Use cases(3) On this page, you can explore some examples of how and where Passkeys is being used today. ## Examples Passkeys provide a seamless and secure way to authenticate users without relying on traditional passwords. You can use the buttons below to explore examples of how you can use Passkeys: * [**Shared computer login**](/docs/passkeys/use-cases/shared-computer-login): Use passkeys to authenticate multiple employees on a shared computer * [**Web login**](/docs/passkeys/use-cases/web-login): Use passkeys to authenticate your end-users on your website --- ## Shared computer login ## Use case You are looking for a secure way for your employees to log in to a shared company computer or shared workstation. Rather than dealing with shared passwords, forgotten passwords, or cumbersome One-Time Passwords (OTPs), employees can use a passkey stored on their own personal mobile device to quickly and securely log in to the shared workstation. :::note Note This use case relies on **cross-device authentication** which bridges the gap between the shared computer and the end-user's personal mobile device, while maintaining high security. ::: ## How it works Meet Jane, one of your active employees who has set up a passkey on their personal mobile device for your company portal. Jane needs to log in to a shared computer at the office to access your internal services. 1. Jane visits your internal portal on the shared computer and clicks the login button. 2. The browser displays a QR code and prompts her to use a passkey from another device. 3. Jane scans the QR code using her mobile device's camera. 4. Her mobile device connects via Bluetooth to verify proximity and prompts her to authenticate using her passkey. 5. Jane uses her mobile device's local authentication to approve the login. :::info What does this mean? An example of a local authentication on the mobile device could be Face ID or Touch ID. ::: 6. The authentication is successful, and Jane is logged into the internal portal on the shared computer. :::note Success! Jane has now securely authenticated herself on the shared computer using her personal mobile device, without needing a password. ::: ## What it looks like The following diagram illustrates what the cross-device authentication flow could look like using a passkey from the perspective of an employee. ### Cross-device authentication ## Implementation :::tip Note This flow assumes that you are using ReuseID with Passkeys authentication, and that the employee has an active ReuseID user with a registered passkey on their personal device. ::: The following flow is a suggestion on how to implement passkey authentication for a shared computer, leveraging the Signicat ReuseID API: 1. The employee initiates the login process by clicking a button on the shared computer's browser. 2. Your server starts an authentication process by calling the Signicat ReuseID API. 3. Signicat generates a challenge and returns an `idpRedirectUri`. 4. The shared computer opens the `idpRedirectUri`, which prompts the browser to request a passkey authentication. 5. The employee authenticates by scanning a QR code with their personal mobile device. 6. The personal mobile device authenticator generates an assertion and sends it to Signicat. 7. Signicat verifies the assertion and redirects the browser on the shared computer to your specified redirect URL upon completion. 8. Signicat sends a callback to your server containing the authentication response. 9. Your server grants the employee access to their account on the shared computer based on the callback. ### Sequence diagram ```mermaid sequenceDiagram title Passkey shared computer login actor user as Employee participant client as Shared computer browser participant device as Employee'smobile device participant server as Your server participant signicat as ReuseID (Passkeys) user->>client: Initiates login client->>server: Start login process server->>signicat: POST /authentications signicat-->>server: Returns idpRedirectUri and transactionId server-->>client: Redirect URL (idpRedirectUri) client->>signicat: Opens idpRedirectUri signicat->>client: Request passkey authentication (Shows QR) user->>device: Scans QR code device->>user: Prompt for passkey(Local auth) note over user, device: Employee authenticates using biometrics on mobile device user-->>device: Authentication success device->>signicat: Send assertion signicat-->>client: Redirect back to your internal portal signicat->>server: POST /callback with authentication response server-->> signicat: OK note over user, client: Employee is now logged in on shared computer ``` ## Learn more * [**API reference**](pathname:///apis/reuseid/#tag/Passkeys-Authentication): Explore endpoints and properties with example requests and responses --- ## Web login ## Use case You are looking for a secure way for your end-users to authenticate on your website using a passkey. This use case provides a seamless and secure experience without the need for traditional passwords, while maintaining high security. It covers both authenticating on the same device where the passkey is stored, and authenticating across different devices. :::info What is cross-device authentication? For example, this could mean logging into a website on a laptop using a passkey stored on a mobile device. ::: ## How it works Meet Jane, one of your active end-users who has set up a passkey for your service. Jane needs to log in to your website so that she can access your online services. The experience will differ slightly depending on which device she uses to access your website. ### Same device authentication In this scenario, Jane is accessing your website on the same device where her passkey is stored. For example, this could be her her mobile device or a laptop with a built-in authenticator. 1. Jane visits your website and clicks the login button. 2. The browser prompts her to authenticate using her passkey. 3. Jane uses her device's local authentication to approve the login. :::info What does this mean? An example of a local authentication could be: - **Mobile device**: Face ID or Touch ID - **Computer**: Windows Hello ::: 4. The authentication is successful and Jane is logged in. ### Cross-device authentication In this scenario, Jane is accessing your website on a different device than where her passkey is stored. For example, she could be using her laptop, but her passkey is on her mobile device. 1. Jane visits your website on her laptop and clicks the login button. 2. The browser displays a QR code and prompts her to use a passkey from another device. 3. Jane scans the QR code using her mobile device's camera. 4. Her mobile device connects via Bluetooth to verify proximity and prompts her to authenticate using her passkey. 5. Jane uses her mobile device's local authentication to approve the login. :::info What does this mean? An example of a local authentication on the mobile device could be Face ID or Touch ID. ::: 6. The authentication is successful, and Jane is logged into the website on her laptop. :::note Success! Jane has now securely authenticated herself to your website using a passkey. ::: ## What it looks like The following diagram illustrates what an authentication flow could look like using a passkey, from the perspective of your end-user. ### Same device authentication ### Cross-device authentication ## Implementation :::tip Note This flow assumes that you are using ReuseID with Passkeys authentication, and that the end-user has an active ReuseID user with a registered passkey. ::: The following flow is a suggestion on how to implement passkey authentication for a website, leveraging the Signicat ReuseID API: 1. The end-user initiates the login process by clicking a button on your website. 2. Your server starts an authentication process by calling the Signicat ReuseID API. 3. Signicat generates a challenge and returns an `idpRedirectUri`. 4. Your website opens the `idpRedirectUri`, which prompts the end-user's browser to request a passkey authentication. 5. The end-user authenticates either on the current device or by scanning a QR code with another device. 6. The authenticator generates an assertion and sends it to Signicat. 7. Signicat verifies the assertion and redirects the browser to your specified redirect URL upon completion. 8. Signicat sends a callback to your server containing the authentication response. 9. Your server grants the end-user access to their account based on the callback. ### Sequence diagram ```mermaid sequenceDiagram title Passkey web login actor user as End-user participant client as Browser participant server as Your server participant signicat as ReuseID (Passkeys) user->>client: Initiates login client->>server: Start login process server->>signicat: POST /authentications signicat-->>server: Returns idpRedirectUri and transactionId server-->>client: Redirect URL (idpRedirectUri) client->>signicat: Opens idpRedirectUri signicat->>client: Request passkey authentication client->>user: Prompt for passkey(Local authentication or QR code) note over user, client: End-user authenticates using biometrics on device user-->>client: Authentication success client->>signicat: Send assertion signicat-->>client: Redirect back to your website signicat->>server: POST /callback with authentication response server-->> signicat: OK note over user, client: End-user is now logged in ``` ## Learn more * [**API reference**](pathname:///apis/reuseid/#tag/Passkeys-Authentication): Explore endpoints and properties with example requests and responses --- ## Signicat products Browse products designed for your business needs. ### Identity Proofing Verify identities of people and organisations using trusted sources. * [**Data Verification**](/docs/data-verification/): Person and organisation data validation * [**eID and Wallet Hub**](/docs/eid-hub/): Authenticate users and organisations securely with eIDs and identity wallets * [**ID Document and Biometric Verification**](/docs/id-document-and-biometric-verification/): Document authenticity, facial likeness and liveness check * [**Ongoing Monitoring**](/docs/ongoing-monitoring/): Monitor identity data changes * [**ReuseID**](/docs/reuseid/): Reusable identities with identity proofing, authentication and orchestration ### Trust Orchestration Automate and optimise compliant identity and risk workflows. * [**Digital Evidence Management**](/docs/digital-evidence-management/): Evidence of consents and transactions * [**Signicat Mint**](/docs/mint/): No-code builder for compliant end-user journeys ### Authentication Log in users securely and manage access rights. * [**eID and Wallet Hub**](/docs/eid-hub/): Authenticate users and organisations securely with eIDs and identity wallets * [**Encap SCA**](/docs/mobile-identity/encap/): Authenticate and authorise end-user operations securely with your mobile app * [**MobileID**](/docs/mobile-identity/mobileid/): Authenticate and authorise end-user operations securely with your mobile app * [**Passkey**](/docs/passkeys/): Passwordless, biometric authentication directly in your browser * [**ReuseID**](/docs/reuseid/): Reusable identities with identity proofing, authentication and orchestration * [**Signicat IAM**](/docs/siam/): Manage your end-users and create reusable identities globally ### Electronic Signing Get documents signed remotely and manage evidence. * [**Digital Evidence Management**](/docs/digital-evidence-management/): Evidence of consents and transactions * [**Electronic Signing**](/docs/electronic-signing/): Seamless electronic signature integration * [**Qualified Timestamps (QTSA)**](/docs/qtsa/): eIDAS-certified qualified timestamps * [**Secure Share**](/docs/secure-share/): Secure Share enables you to securely share files with other people * [**Signicat Archive**](/docs/signicat-archive/): Securely store and retrieve signed documents ### APIs Explore API reference documentation in the [API overview](/apis/). --- ## Qualified Timestamps (QTSA) Signicat offers Qualified Timestamping Authority (QTSA) services which can be used for issuing a qualified timestamp and binding that timestamp to a data object. The most common use cases are the timestamping of signed documents and the timestamping of documents that are stored in an archive. ## Key security features - Qualified Timestamping Authority services can only be operated by a Qualified Trust Service Provider (QTSP) and require annual audits by internationally accredited third-party auditors. This ensures that qualified timestamps are non-repudiable. :::info What does this mean? According to the [Regulation (EU) No 910/2014 of the European Parliament and of the council on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EC](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32014R0910#d1e791-73-1), the term 'Qualified Trust Service Provider' refers to "a trust service provider who provides one or more qualified trust services and is granted the qualified status by the supervisory body". ::: - Qualified timestamps do not contain sensitive data and are therefore not subject to the [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/). - A timestamping service does not require any electronic identity (eID) and does not hold any GDPR-related data. - The object to be timestamped does not leave your infrastructure. You only pass a SHA256 hash of the data object to be timestamped to the timestamping authority (TSA), not the data object itself. ## Process overview ### Generating a timestamp To generate a timestamp using Signicat's Qualified Timestamping Authority services, follow these steps: 1. Have your data object ready. This can be a file of any type, such as a PDF or an image file. 2. Generate a cryptographic hash of the file or text you want to timestamp. The hashing algorithm will need to be SHA256. 3. Send this hash to the TSA, which retrieves the correct time from trusted time sources and builds a Signed Data Object (SDO) in the form of a `.tsr` file. 4. The timestamp has been generated. The SDO can be kept inside the document (this is the case for electronic signatures), but it can also be kept as a separate object. The following diagram illustrates the generation of a timestamp: Timestamp generation ### Validating a timestamp To validate a timestamp, follow these steps: 1. Have your original data object ready. 2. Take another SHA256 hash of the data object. In our example, this is done by `openssl verify`. 3. Provide the timestamp object (SDO) and the public key certificate of the QTSA for verification. The `.pem` file that contains the certificate to be used is available for download in the [Validating a timestamp (example)](#validating-a-timestamp-example) section on this page. 4. If the document has not been modified, you will receive a positive validation response. Note that the validation does not use the timestamping engine. You can use a service such as `openssl verify`. The following diagram illustrates the validation of a timestamp: Timestamp validation ## Accessing Signicat's QTSA service To get started with Signicat's QTSA service, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. Once you have signed a contract with Signicat and have provided the necessary information, you will be able to access the TSA service at `https://tsa.signicat.com/tsaproxy/`. Access to the service works in accordance with the [Internet X.509 Public Key Infrastructure Time-Stamp Protocol (RFC3161)](https://joinup.ec.europa.eu/collection/belgian-interoperability-catalogue/solution/tunnel-setup-protocol/distribution/rfc3161-internet-x509-public-key-infrastructure-time-stamp-protocol-tsp), which is the common way of accessing any TSA service. Most programming languages have support for RFC3161 through open source libraries. :::tip Note The interface is the same for both TSA and QTSA. It is common to use a free TSA for testing and then move to the QTSA in production. ::: ## Examples of timestamp generation and validation To run these examples, you will need to have [OpenSSL](https://www.openssl.org/) and [cURL](https://curl.se/) installed on you computer. ### Generating a timestamp (example) 1. Generate a timestamp query file (`.tsq`) that includes a hash of the data to be timestamped. The example below uses OpenSSL for this operation. 2. Send the query file to the TSA. 3. The TSA produces a signed timestamp response file (`.tsr`). Most commonly, this file will be about 1 kB in size and it will be signed and secured in such a way that it cannot be modified. ```bash #!/bin/bash #Generate request file based on Example.xlsx echo "Generating .tsq file (query file with hash)" openssl ts -query -data anyfile -cert -sha256 -no_nonce -out Exampleqtsa.tsq echo "" echo "Generating Timestamp into Eaxmpleqtsa.tsr file" curl -v -s -S -H 'Content-Type: application/timestamp-query' --data-binary @Exampleqtsa.tsq 'https://tsa.signicat.com/tsaproxy/' -o Exampleqtsa.tsr ``` ### Validating a timestamp (example) Validation of a timestamp requires: - The timestamp object (`.tsr` file) - The public key certificate, contained in a `.pem` file. The public key certificate for Signicat's QTSA is available through the [EU Trust Services Dashboard](https://esignature.ec.europa.eu/efda/tl-browser/#/screen/tl/NO/14). You can find the `.pem` file that contains the certificate here: [**Download public key certificate**](/uploaded-media/certificates/qtsa/signicat_public_key_certificate.pem) The example below uses OpenSSL to verify the public key certificate. ```bash #!/bin/bash #Generate request file based on Example.xlsx echo "" echo "Validate" openssl ts -verify -data anyfile -in Exampleqtsa.tsr -CAfile signicat_public_key_certificate.pem echo "" echo "Dump of timestamp data" openssl ts -reply -in Exampleqtsa.tsr -text ``` --- ## Changelog Documentation will be available here soon. --- ## Flutter Documentation will be available here soon. --- ## Introduction to ReadID Ready Documentation will be available here soon. --- ## Introduction to ReadID SDK Documentation will be available here soon. --- ## About ReadID ## Familiarise yourself with ReadID * [**Introduction to ReadID SDK**](/docs/readid/about-readid/get-started-readid-sdk): Introduction to ReadID SDK. * [**Introduction to ReadID Ready**](/docs/readid/about-readid/get-started-readid-ready): Introduction to ReadID Ready. * [**Training documents**](/docs/readid/about-readid/training-documents): Access training documents from Utopia. * [**Security and Compliance**](/docs/readid/about-readid/security-and-compliance): Learn about security and compliance. * [**Whitepapers**](/docs/readid/about-readid/whitepapers): Read our whitepapers. * [**Changelog**](/docs/readid/about-readid/changelog): View the latest updates and changes. * [**React Native**](/docs/readid/about-readid/react-native): Documentation for React Native. * [**Flutter**](/docs/readid/about-readid/flutter): Documentation for Flutter. --- ## React Native Documentation will be available here soon. --- ## Security and compliance Documentation will be available here soon. --- ## Training documents Documentation on training documents from Utopia will be available here soon. --- ## Whitepapers Documentation will be available here soon. --- ## ReadID ## Introduction ReadID is an identity verification technology that uses NFC (Near Field Communication) to read the secure chip in electronic passports, ID cards, and residence permits. ## Supported features ReadID supports the following identity verification features: - ID document check - NFC reading of ID document's chip - Face match between ID document and selfie - Liveness check of live video recording ## Product types ReadID has two product types, **ReadID SaaS SDK** and **ReadID Ready**, so you can choose the one that best suits your organisation.
Which product type is right for you? Compare them here. :::CustomTable{columnWidths="10% 45% 45%" minTableSize="850px"} | Topic | ReadID SaaS SDK | ReadID Ready | | -------------------- | ------------------------------| ---------------------------------------- | | Integration | Integrate directly into your own mobile app using our SDKs and APIs. | A ready-to-use application for web flows. | | Customisation | Offers full control over the user interface and branding for a seamless user experience. | A configurable app that can be quickly deployed with minimal setup. | | Use case | Ideal for organisations with an existing mobile app that want to provide a fully branded and integrated identity verification process. | Perfect for businesses that do not have their own mobile app or for those who need a quick and easy way to verify identities through a web-based flow. | | Developer effort | Requires development effort to integrate the SDK into your application and build the user interface. | Minimal developer effort is needed as it is a pre-built application. | | User journey | The user remains within your app during the entire verification process. | Users are redirected to the ReadID Ready application to complete the verification and then returned to your service. | :::
## Upcoming ReadID documentation * [**About ReadID**](/docs/readid/about-readid/): General information, compliance and whitepapers. * [**ReadID SaaS SDK**](/docs/readid/readid-saas-sdk/): Documentation and guides for the ReadID SaaS SDK. * [**ReadID Ready**](/docs/readid/readid-ready/): Documentation and guides for ReadID Ready. * [**Orchestration**](/docs/readid/orchestration/): Links to external identity verification providers and resources. --- ## Orchestration ## Explore documentation for third-party providers * [**iProov**](/docs/readid/orchestration/iproov): Documentation for iProov. * [**Veriff**](/docs/readid/orchestration/veriff): Documentation for Veriff. --- ## iProov Documentation will be available here soon. --- ## Veriff Documentation will be available here soon. --- ## ReadID Ready ## Explore ReadID Ready * [**ReadID Ready (Native)**](/docs/readid/readid-ready/readid-sdk-native/): Documentation for ReadID Ready (Native). * [**ReadID Ready (Assure)**](/docs/readid/readid-ready/readid-sdk-assure/): Documentation for ReadID Ready (Assure). --- ## ReadID Ready (Assure) :::info Integration option As an alternative to using the ReadID native APIs, you can also integrate ReadID through the Assure API. Documentation for this will follow later. ::: --- ## Business rules results Documentation will be available here soon. --- ## IAM user management Documentation will be available here soon. --- ## ReadID SDK (Native) ## Explore ReadID SDK (Native) * [**Services overview**](/docs/readid/readid-ready/readid-sdk-native/services-overview): Services overview. * [**Business rules results**](/docs/readid/readid-ready/readid-sdk-native/business-rules-results): Business rules results. * [**IAM user management**](/docs/readid/readid-ready/readid-sdk-native/iam-user-management): Documentation for IAM user management. * [**Sample code for App2App flow**](/docs/readid/readid-ready/readid-sdk-native/sample-code-for-app2app-flow): Sample code for App2App flow. * [**Sample code for desktop QR code & MobileWeb2App**](/docs/readid/readid-ready/readid-sdk-native/sample-code-for-desktop-qr-code-and-mobileweb2app): Sample code for desktop QR code and MobileWeb2App. * [**Server API documentation**](/docs/readid/readid-ready/readid-sdk-native/server-api-documentation): Documentation for the Server API. * [**Management portal admin guide**](/docs/readid/readid-ready/readid-sdk-native/management-portal-admin-guide): Management portal admin guide. --- ## Management portal admin guide Documentation will be available here soon. --- ## Sample code for App2App flow Documentation will be available here soon. --- ## Sample code for desktop QR code & MobileWeb2App Documentation will be available here soon. --- ## Server API documentation Documentation will be available here soon. --- ## Services overview Documentation will be available here soon. --- ## ReadID SaaS SDK(Readid-saas-sdk) ## Explore ReadID SDKs * [**ReadID SDK (Native)**](/docs/readid/readid-saas-sdk/readid-sdk-native/): Documentation for ReadID SDK (Native). * [**ReadID SDK (Assure)**](/docs/readid/readid-saas-sdk/readid-sdk-assure/): Documentation for ReadID SDK (Assure). * [**iProov SDK**](/docs/readid/readid-saas-sdk/iproov-sdk): Documentation for iProov SDK. --- ## iProov SDK Documentation will be available here soon. --- ## ReadID SDK (Assure) :::info Integration option As an alternative to using the ReadID native APIs, you can also integrate ReadID through the Assure API. If you want to integrate through the Assure API instead, please see the [ID Document and Biometric Verification documentation](/docs/id-document-and-biometric-verification/assure-api/). ::: --- ## Business rules results(Readid-sdk-native) Documentation will be available here soon. --- ## DocC Documentation will be available here soon. --- ## Dokka Documentation will be available here soon. --- ## IAM user management(Readid-sdk-native) Documentation will be available here soon. --- ## ReadID SDK (Native)(Readid-sdk-native) ## Explore ReadID SDK (Native) * [**Services overview**](/docs/readid/readid-saas-sdk/readid-sdk-native/services-overview): Services overview. * [**Business rules results**](/docs/readid/readid-saas-sdk/readid-sdk-native/business-rules-results): Business rules results. * [**IAM user management**](/docs/readid/readid-saas-sdk/readid-sdk-native/iam-user-management): Documentation for IAM user management. * [**Management portal admin guide**](/docs/readid/readid-saas-sdk/readid-sdk-native/management-portal-admin-guide): Management portal admin guide. * [**Server API documentation**](/docs/readid/readid-saas-sdk/readid-sdk-native/server-api-documentation): Documentation for the Server API. * [**Technical guide**](/docs/readid/readid-saas-sdk/readid-sdk-native/technical-guide): Technical guide. * [**Dokka**](/docs/readid/readid-saas-sdk/readid-sdk-native/dokka): Documentation for Dokka. * [**DocC**](/docs/readid/readid-saas-sdk/readid-sdk-native/docc): Documentation for DocC. * [**Sample code**](/docs/readid/readid-saas-sdk/readid-sdk-native/sample-code): Sample code. --- ## Management portal admin guide(Readid-sdk-native) Documentation will be available here soon. --- ## Sample code Documentation will be available here soon. --- ## Server API documentation(Readid-sdk-native) Documentation will be available here soon. --- ## Services overview(Readid-sdk-native) Documentation will be available here soon. --- ## Technical guide Documentation will be available here soon. --- ## ReuseID API references In our ReuseID API references, you can find information about the available endpoints and properties, as well as sample requests and responses. * [**ReuseID Onboarding API**](/apis/reuseid-onboarding/): Use ready-made flows to onboard ReuseID identities and perform step-up operations * [**ReuseID API**](/apis/reuseid/): Manage identities and carry out ReuseID authentication operations --- ## Authentication Authentication is what transforms ReuseID from a one-time identity proofing operation into a reusable identity. It enables you to provide secure and frictionless authentication experiences wherever your end-users need them. Currently, you can choose between [MobileID](#mobileid) and [Passkeys](#passkeys) as the authentication method. You can also combine both authentication methods to offer flexible, secure authentication across all channels. ## MobileID ReuseID with MobileID authentication allows you to authenticate your end-users securely using your mobile app. :::tip Our recommendation We recommend that you use this authentication method if you have a mobile app or are pursuing a mobile-first strategy. ::: * [**MobileID authentication**](/docs/mobile-identity/mobileid): Learn more about MobileID in our developer documentation ## Passkeys ReuseID with Passkeys authentication allows you to authenticate authorise end-users securely within a browser. :::tip Our recommendation We recommend that you use this authentication method if you interact primarily with your end-users in a browser and are looking to replace traditional passwords. ::: * [**Passkeys authentication**](/docs/passkeys): Learn more about Passkeys in our developer documentation --- ## Best practices(Reuseid) This page contains useful information about best practices and considerations for anyone involved in implementing ReuseID, for example developers, project managers and technical architects. The scope is for select topics that can assist you during your integration, such as key decisions, tips and ways to avoid common issues. ## MobileID authentication If you have chosen MobileID as an authentication method for ReuseID, then you can read the sections below to ensure that you have a smooth and successful integration. ### Choose an authentication protocol An early decision that you need to make is which authentication protocol to use for MobileID authentication: | **Authentication protocol** | **Description** | | :-- | :-- | | ReuseID REST API | The ReuseID REST API is Signicat's native, proprietary solution. You need to use this API to conduct most supported operations, regardless of which authentication protocol you choose. This includes operations such as:
  • Creating ReuseID users
  • Registering MobileID devices
  • Conducting management operations
This means that if you use this API for authentication, then it is the only API you need to support.

**Note**: To learn more, see the [ReuseID API reference](/apis/reuseid/) documentation. | | OIDC Authorization Code Flow | The OpenID Connect (OIDC) authentication protocol with Authorization Code Flow allows you to integrate with MobileID as an eID method in the Signicat eID and Wallet Hub. This is an alternative to integrating with Signicat's ReuseID REST API.

The OIDC Authorization Code Flow is primarily designed for web applications and is not well suited for native mobile apps. In this flow, the client redirects the end-user to the authorisation server for authentication.

**Note**: To learn more, see the MobileID [Authorization Code](/identity-methods/mobileid/integration-guides/oidc/authorization-code-flow/) Flow integration documentation. | | OIDC CIBA Flow | The OpenID Connect (OIDC) authentication protocol with CIBA flow allows you to integrate with MobileID as an eID method in the Signicat eID and Wallet Hub. This is an alternative to integrating with Signicat's ReuseID REST API.

The OIDC CIBA flow (Client-Initiated Backchannel Authentication) is an extension to the OIDC protocol and is well-suited for headless applications that need to make backchannel authentication requests, such as with a mobile app.

This flow may be useful if for example you use a third-party access management software that integrates with and uses OIDC standards.

**Note**: To learn more, see the MobileID [CIBA Flow](/identity-methods/mobileid/integration-guides/oidc/ciba-flow/) integration documentation. | ### Check for outstanding transactions In an omnichannel environment, transactions can be initiated from several different channels and not only from the native mobile app. When your app initiates an authentication, it cancels any ongoing transactions that were started from other channels. To avoid this, you must implement a check for outstanding transactions by using a `startAuth` SDK call before your app starts an authentication itself. ### Avoid excess devices for a user In certain situations, the amount of devices registered to an end-user may be unnecessarily large. For example, this can happen if an end-user deletes and registers your app repeatedly. In these cases, you may reach the user device limit of 30 devices per end-user. If an end-user has more than 30 devices registered to them, then it could indicate suspicious behaviour such as malicious usage of your services. As a security measure: 1. When an end-user attempts to register a device that exceeds the user device limit, we notify you by returning the error message `exceeding_user_device_limit`. 2. Next, you can then investigate the situation further and if required, delete the previously registered devices using the [**Delete device**](pathname:///apis/reuseid/#tag/MobileID-device-management/operation/getDevice) operation. Signicat automatically deletes devices that have not been used in the last 365 days, whereas you must manually delete other devices. :::tip Our recommendation You may find it useful to implement functionality where your end-users can manage their own devices logged into your website and delete their unused devices. ::: ### Activation code length The default activation code length is `10`. To ensure that you maintain good security, we do not recommend that you reduce this length for production accounts. If the end-user registers within your app and does not need to enter the activation code manually, then we recommend that you use a long activation code. ## Passkeys authentication If you have chosen Passkeys as an authentication method for ReuseID, you can read the sections below to ensure a smooth and successful integration. ### Handling redirects and Content Security Policy (CSP) When a passkey registration or authentication finishes, the end-user's browser carries out the final redirect to your provided `rpRedirectUri`. As this is a client-side action, you must account for browser security policies and verify that the operation was successfully completed. :::warning Important The end-user is redirected to the landing page in the `rpRedirectUri` regardless of the outcome of the registration or authentication operation.

That is why this page must never grant access or assume success without verifying that the operation was successfully completed. ::: If your `rpRedirectUri` redirects to another host or domain, the browser's Content Security Policy (CSP) will block it, whereas redirecting to another page on the same server usually works. ```text title="Example: Redirect blocked by CSP" From: https://www.mydomain.com To: https://mydomain.com ``` ```https title="Example: Redirect not blocked by CSP" From: https://www.mydomain.com/first-page To: https://www.mydomain.com/second-page ``` If the browser's CSP blocks the redirect, the end-user may see an error page or appear stuck. However, the underlying passkey operation has already completed on the backend. As this is a browser-side redirect failure, it does not appear in the Signicat audit logs or API responses. :::tip Our recommendation As you cannot see browser-side redirect failures in the Signicat audit logs or API responses, we recommend that you test your redirect flow end-to-end before deploying to production. ::: ### Clearing browser cookies If the end-user's browser becomes unresponsive or appears stuck during a passkeys operation, then we recommend that you ask the end-user to clear their browser cookies and to try again. As this is a browser-side issue, no error message is generated, and it does not appear in the Signicat audit logs or API responses. ## Choose events (callback) or polling Events are our way of letting you know when something happens in one of our services. When an asynchronous operation completes, or when ReuseID gets a notification that a device has changed state, ReuseID publishes an event with the operation result. You can use the Signicat events service to subscribe to events, so that you automatically receive the result at your specified notification URI. This is often referred to as callback. You can also get the operation result back through polling. The result that you receive through the Signicat events service is the same as the result obtained by polling, but wrapped in a Signicat event object. For production, we always recommend that you use the Signicat events service instead of polling. This offers the best usability and responsiveness, as it has the least amount of latency. It also means that you do not need to conduct additional polling calls. :::note Want to learn more? - For information generic to all Signicat events, see the general [Events](/docs/dashboard/settings/events.mdx) documentation. - For information specific to ReuseID, see the ReuseID [Events](/docs/reuseid/events/) documentation. ::: ## Segments When conducting certain operations on the **User** resource, it is possible to pass an optional parameter called `segment` in the request. The following operations support this parameter: - [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) - [**Update user**](pathname:///apis/reuseid/#tag/User/operation/updateUser) As the `segment` is then returned in the response of a respective transaction, it allows you to group the end-users and corresponding transactions based on a segmentation of your choice. For example, if your app is used by end-users across multiple countries, you could use segments to get statistics for app usage per country, In this example, you could segment your end-users using country codes such as `NO`, `SE`, `DK`. ## Resolve an external reference When a user is created with the [**Create user**](pathname:///apis/reuseid/#tag/User/operation/addUser) operation, we generate a valid UUID to identify it called a `userId`. This is required for carrying out most operations such as registration and authentication. You may already have your own internal customer references that you store and use for your customers. In the context of this product, we refer to it as an external reference. If you do not want to store the Signicat-generated `userId`, then you can use the [**Resolve external reference**](pathname:///apis/reuseid/#tag/User/operation/resolveUserIDByExtref) operation to supply the associated `externalRef` and fetch the `userId`. Once fetched, the `userId` can then be can then be used to start the subsequent operation as normal. --- ## Data retention This page provides an overview of the different types of data that could be stored and their retention duration when using our ReuseID solution. In the tables below, all data with the **Data location** marked as **Signicat** is stored on GCP (Google Cloud Platform) Netherlands, with a backup site in Finland. :::note Note This page provides an overview of all data that can be stored. This means that depending on your implementation, not all data may be relevant to you. ::: ## Data relationship diagram The following diagram illustrates how the different data types stored in ReuseID are related: ```mermaid erDiagram Accounts ||--o{ "Account configurations" : "" Accounts ||--o{ "Application configurations" : "" Accounts ||--o{ "ReuseID users" : "" "Account configurations" ||--o{ "Account attributes" : "" "ReuseID users" ||--o{ "User attributes" : "" "ReuseID users" ||--o{ "ID verifications" : "" "ReuseID users" ||--o{ Passkeys : "" "ReuseID users" ||--o{ "MobileID devices" : "" "MobileID devices" }o--o{ "Face maps" : "" "MobileID devices" ||--o{ "Generated secrets" : "" "MobileID devices" ||--o{ "Recovery data" : "" "MobileID devices" ||--o{ "MobileID transactions" : "" Passkeys ||--o{ "Passkeys transactions" : "" "Database backups" "Audit logs" "Face authentication usage logs" ``` ## ReuseID In the table below, you can read about the retention of data associated with ReuseID: :::CustomTable{columnWidths="20% 15% 35% 30%" tableName="ReuseID data retention"} | **Data location** | **Data type** | **Retention time** | **Additional information** | | :-- | :-- | :-- | :-- | | Signicat | Accounts | Deleted immediately when the account entry is set to a `DEACTIVATED` state. **Note**: The account is also automatically set to a `DEACTIVATED` state after 30 days of it being `DISABLED`. | The following child elements are also deleted: Application configurationsAccount configurations:AttributesReuseID users:AttributesMobileID devicesPasskeysID verifications | | Signicat | ReuseID users | Retained for 60 days after the user entry is set to a `DELETED` state. | The following child elements are also deleted: Attributes MobileID devices Passkeys ID verifications | | Signicat | Database backups | Retained for 30 days. | | | Signicat | Audit logs | Retained for 365 days. | | ::: ## MobileID authentication In the table below, you can read about the retention of data associated with MobileID authentication for ReuseID: :::CustomTable{columnWidths="20% 15% 35% 30%" tableName="MobileID authentication data retention"} | **Data location** | **Data type** | **Retention time** | **Additional information** | | :-- | :-- | :-- | :-- | | Signicat | MobileID devices and their data | Retained for 60 days after the MobileID device entry is set to a `DELETED` state. **Note**: The device is also automatically set to a `DELETED` state after 365 days of inactivity. | | | Signicat | MobileID transactions | Retained for 60 days. | | | Signicat | MobileID application configurations | Retained until the account is deleted. | To learn more, see data type **Accounts** in the [ReuseID](#reuseid) table. | | Signicat | Face authentication face maps | Retained until the last associated MobileID device is deleted, subject to the 60-day device retention period. | | | Signicat | Face authentication usage logs | Retained for 60 days, as required by FaceTec. | The usage logs are anonymous and contain no personally identifiable information (PII). To learn more, see [Usage logs](https://dev.facetec.com/usage-logs) in the FaceTec developer documentation. | | End-user's device | Generated secrets Generated data (other) | Retained until the end-user deletes the app. | | | End-user's Google Cloud backup | Recovery data | Retained until the end-user deletes the app. | | | End-user's Apple iCloud Keychain | Recovery data | Retained indefinitely in iCloud Keychain, but becomes inaccessible upon app deletion. | This is because the encryption key is stored with the app and deleted with it. | ::: ## Passkeys authentication In the table below, you can read about the retention of data associated with Passkeys authentication for ReuseID: :::CustomTable{columnWidths="20% 15% 35% 30%" tableName="Passkeys authentication data retention"} | **Data location** | **Data type** | **Retention time** | **Additional information** | | :-- | :-- | :-- | :-- | | Signicat | Passkey public key Passkey metadata | Retained for 60 days after the passkey entry is set to a `DELETED` state. **Note**: The passkey is also automatically set to a `DELETED` state after 365 days of inactivity. | | | Signicat | Passkeys transactions | Retained for 60 days. | | ::: --- ## Error codes(Reuseid) When you make a request to Signicat's ReuseID API and there is an error, a response with an error object is returned. If you have encountered an error, check the information on this page to investigate what might have caused the error and how to resolve it. If you require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::note Error object and generic error codes In addition to these product-specific error codes, there are generic error codes which are applicable to all Signicat APIs. To learn about these and how the error object looks, see our generic [Error codes](/docs/dashboard/error-codes.mdx) documentation. ::: ## ReuseID error object For ReuseID, the error object can be made up from the following 7 fields: | **Field name** | **Description** | **Type/format requirement** | | :-- | :-- | :-- | | `type` | URI to the documentation that describes the error. | String | | `title` | A summary of the error type (this does not change between occurrences of the error). | String | | `code` | A machine-readable string, indicating the error code. This is a constant. | String | | `status` | The HTTP status code generated by the origin server (specific to this occurrence of the error). | HTTP status code | | `traceId` | The unique identifier of the request in the tracing system. This makes it possible for us to trace the history of the request in detail. | String | | `detail` | An explanation of the error (specific to this occurrence of the error). | String | | `invalidParams` | List of request parameters that have failed the validation. Contains the parameter name and the reason for validation failure. | String | ### Example responses ```json title="Example 1: ReuseID response with error object" { "type": "https://api.signicat.com/reuseid/core/openapi.json", "title": "User entity does not exist", "code": "user_entity_does_not_exist", "status": 404, "traceId": "4bf239c088089f2bca77d3a413909f1d", "detail": "Failed fetching user with user ID : 90e1b3e5-93a7-458e-b42b-d1b57e65e26a and account ID : a-sdge-Abcdefghijk123456789." } ``` :::details What does this example mean? In this example, we can determine that the user entity (referred to by the `userId` in the request) does not exist. The `detail` describes which user ID and account ID this refers to, so that you can take action accordingly. ::: ```json title="Example 2: ReuseID response with failed validation of request parameters" { "type": "https://api.signicat.com/reuseid/core/openapi.json", "title": "Invalid request parameter", "code": "invalid_request_parameter", "status": 400, "traceId": "4bf239c088089f2bca77d3a413909f1d", "detail": "Your request body parameters have failed validation." "invalidParams": [ { "name": "userId" "reason": "userId cannot be null or empty" }, { "name": "deviceId" "reason": "deviceId cannot be null or empty" } ] } ``` :::details What does this example mean? In this example, we can determine that multiple request parameters have failed the validation. The `invalidParams` describes which request parameters have failed the validation, so that you can modify them to pass the validation. ::: ## ReuseID error codes ReuseID can return generic, MobileID-specific and Passkey-specific errors. To learn about the different types of errors that you can receive, see the sections below. ### Generic error codes The following errors are generic and can describe a number of possible issues: | **Error code** | **HTTP Status** | **Description** | | :-- | :-- | :-- | | `access_token_missing` | 401 | The access token is missing from the request. | | `internal_error` | 500 | An internal error that requires no action from you. **Note**: In the rare case that this error persists, contact us by creating a support ticket in the [Signicat Dashboard](https://dashboard.signicat.com/contact-us/tickets/new). | | `internal_subsystem_error` | 4xx50x | An internal error that requires no action from you. **Note**: In the rare case that this error persists, contact us by creating a support ticket in the [Signicat Dashboard](https://dashboard.signicat.com/contact-us/tickets/new). | | `invalid_request` | 400404405406415 | A generic error that indicates the request is invalid. There are a number of possible causes for this error, such as: If a required query parameter is missing. If the wrong HTTP operation type is sent. | | `request_parsing_error` | 400 | There was an error when parsing the request, due to invalid JSON formatting. | | `unknown_property` | 400 | The property being passed in the request is either incorrect or misspelled. **Note**: You This error is also returned if the property being passed is correct, but its placement in the request is incorrect. | | `missing_identifier` | 400 | The device ID (`deviceId`) or user ID (`userId`) are missing in the resource path. | | `missing_request_parameter` | 400 | The device object, device ID (`deviceId`), or user ID (`userId`) are missing in the request payload. | | `invalid_request_parameter` | 400404 | A generic error that indicates the request contains an invalid parameter, or that no parameter has been supplied. There are a number of possible causes for this error, such as: If no parameter is supplied when you are resolving the external reference with an API call (`externalRef = null`). If the enumerated values being passed are not valid (if they are incorrect, or do not belong to the allowed set of values). | | `invalid_identifier` | 400404 | The supplied identifier uses an invalid character. For universally unique identifiers (UUIDs): User ID (`userId`) Device ID (`deviceId`) The allowed character set is: `REGEX = \"^[a-z0-9][a-z0-9\\-]*$\";` For other identifiers: External reference (`externalRef`) Attribute name (`attrName`) The allowed character set is: `REGEX = \"^[a-z_0-9][a-z_0-9~\\.\\-:@]*$\";` | | `identifier_too_long` | 400 | The supplied identifier exceeds the maximum character length. Maximum character lengths: External reference (`externalRef`): 128 characters Attribute name (`attrName`): 128 characters Attribute value (`attrValue`): 256 characters Any universally unique identifier (UUID): 36 characters | | `user_entity_does_not_exist` | 404 | The user entity referred to by the user ID (`userId`) does not exist. | | `user_entity_is_locked` | 409 | The user entity referred to by the user ID (`userId`) does exist, but is in a `LOCKED` state, and is therefore invalid for the requested operation. | | `user_entity_already_exists` | 409 | A new user entity cannot be added, as the user entity with that external reference (`externalRef`) already exists for this account. | | `transaction_id_does_not_exist` | 404 | The transaction (with the transaction ID specified for this `GET` API call) cannot be found. | | `invalid_operation` | 400403404 | The operation cannot be cancelled, as the session for this operation does not exist. | | `exceeding_user_attribute_limit` | 400 | The maximum limit for the number of user attributes (100) has been exceeded. | | `multiple_pending_proofings` | 500 | There are multiple pending proofings. | | `user_proofing_does_not_exist` | 404 | The user proofing does not exist. | ### MobileID error codes The following errors are specific to when you are using **MobileID** as the authentication method: | **Error code** | **HTTP Status** | **Description** | | :-- | :-- | :-- | | `device_does_not_exist` | 404 | The device referred to by the device ID (`deviceID`) does not exist. | | `device_is_locked` | 400 | The device referred to by the device ID (`deviceID`) does exist, but is in a `LOCKED` state. This means that it is invalid for the requested operation. | | `exceeding_user_device_limit` | 400 | The maximum limit for the number of user devices (30) has been exceeded. | | `exceeding_sandbox_device_limit` | 405 | The maximum limit for the number of sandbox devices (100) has been exceeded. | ### Passkeys error codes The following errors are specific to when you are using **Passkeys** as the authentication method: | **Error code** | **HTTP Status** | **Description** | | :-- | :-- | :-- | | `passkey_id_does_not_exist` | 404 | The passkey ID does not exist. | --- ## Events (callback)(Reuseid) Events are our way of letting you know when something happens in one of our services. ReuseID events are a type of Signicat event that are specific to the ReuseID service. For example, a ReuseID event is generated when an authentication result is ready. :::info Learn about Signicat events This page focuses on ReuseID events. For general information about Signicat events and the events service, see our [Events and webhooks](/docs/dashboard/settings/events.mdx) documentation. ::: ## How do ReuseID events work? When an asynchronous operation completes, or when ReuseID gets a notification that a device has changed state, ReuseID publishes an event with the operation result. If you have subscribed to the event, then you automatically receive the result at your specified notification URI. This is often referred to as callback. You can also get the operation result back through polling. The result that you receive through the Signicat events service is the same as the result obtained by polling, but wrapped in a Signicat event object. ### When to use callback We recommend that you always set up callback for production. This offers the best usability and responsiveness as it has the least amount of latency, and means that you do not need to conduct additional polling calls. ### When to use polling Regardless of whether callback is set up or not, you can fetch the result of a completed operation from Signicat by polling. You can do this by running GET API calls, but it should only be reserved for testing and development use. ## Which events does ReuseID publish? ReuseID publishes events for the authentication methods that it supports and for operations related to managing these authentication methods. For an overview of the events that you can subscribe to, see the tables in the sections below: ### MobileID ReuseID events related to the MobileID service, such as: - Authentication - Registering and managing MobileID devices - Account recovery :::CustomTable{columnWidths="25% 15% 60%" tableName="ReuseID events with MobileID authentication"} | **Event name** | `eventName` | **Description** | | :-- | :-- | :-- | | MobileID Device account recovery completed | `device.account-recovery.completed` | When a device operation to perform an account recovery is completed. **Note**: This is a device operation carried out by the end-user. | | MobileID Device account recovery state change | `device.account-recovery.state.change` | When a device operation to add or delete account recovery is completed. **Note**: This is a device operation carried out by the end-user. | | MobileID Device authentication completed | `device.authentication.completed` | When an operation to authenticate with MobileID is completed. | | MobileID Device registration completed | `device.registration.completed` | When an operation to register a new MobileID device is completed. | | MobileID Device signature completed | `device.signature.completed` | When an operation to sign with MobileID is completed. | | MobileID Device state change | `device.state.change` | When an operation to change the state of a MobileID device is completed. **Note**: This is a device operation that happens when the device is locked or deactivated by an external action. For example: The device can be **locked** if the end-user enters an incorrect PIN too many times in a row. The device can be **deactivated** by the device SDK. The device can be **deactivated** by the periodic cleanup job if the device has been inactive for too long, such as one year. | ::: ### Passkeys ReuseID events related to the Passkeys service, such as: - Authentication - Registering a passkey - Managing a passkey :::CustomTable{columnWidths="25% 15% 60%" tableName="ReuseID events with Passkeys authentication"} | **Event name** | `eventName` | **Description** | | :-- | :-- | :-- | | Passkey authentication completed | `passkey.authentication.completed` | When an operation to authenticate with Passkeys is completed. | | Passkey registration completed | `passkey.registration.completed` | When an operation to register a new passkey is completed. | | Passkey state change | `passkey.state.change` | When an operation to change the state of a passkey is completed. | ::: ## What do ReuseID events look like? Events follow the same structure across all Signicat services, with the exception of the event data (`eventData`) field. This field varies depending on the type of event, as it is where we pass the operation result as a JSON object. You can find an overview of a ReuseID event in the table below: :::CustomTable{columnWidths="25% 40% 15% 20%" tableName="ReuseID event structure"} | **Field name** | **Description** | **Type** | **Example** | | :-- | :-- | :-- | :-- | | `id` | The ID of the event. | String | `13a816b4-f6f3-4424-907c-a95e234155b2` | | `timestamp` | The timestamp when the event was created. | ISO 8601 date string | `2024-07-02T12:53:13.659Z` | | `eventName` | The name of the event. | String | `registration.completed` | | `sender` | The service which is sending the event | String | `reuseid` | | `eventData` | The event data. | JSON | _JSON object with event data._ | | `accountId` | The account ID which the event is sent in the context of. | String | `a-ppge-abcdefeghijklmn12345` | | `expiresAt` | The timestamp when the event expires. **Note**: There are no more retries after this timestamp. | ISO 8601 date string | `2024-07-02T12:58:13Z` | | `tags` | Optional tags that can be included in the event. **Note**: You add tags by setting them in the request to the service publishing the events. | String array | _Empty list._ | ::: ## How to subscribe to ReuseID events You can use the Signicat Dashboard to subscribe to the events that you would like to receive callback for. ReuseID uses the MobileID and Passkeys services for authentication. Both of these services publish their own events which you can subscribe to in the Signicat Dashboard, but they do not contain the full set of ReuseID information. To get the complete ReuseID MobileID/Passkeys event information, you need to subscribe to the MobileID and Passkeys events published by the ReuseID service, not to the events published directly by the MobileID and Passkeys services. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Events**](https://dashboard.signicat.com/events). 2. Click the **+Add subscription** button. 3. Select a subscription type, for example **Webhook**. 4. Complete the required fields. In the **Listen to** section, under the **ReuseID** section, select the events that you want to subscribe to. 5. Click the **Add** button. :::info Want to learn more? To learn more about subscribing to and managing events, see the [Events and webhooks](/docs/dashboard/settings/events.mdx) page in the Signicat **Dashboard** documentation. ::: ## How to preview ReuseID events You can preview what the JSON payload looks like for each event in the Signicat Dashboard when you set up a new subscription. To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Events**](https://dashboard.signicat.com/events). 2. Click the **+Add subscription** button. 3. Select a subscription type, for example **Webhook**. 4. Under the **Listen to** section, click **Selected events**, then expand the **ReuseID** dropdown menu. 5. Hover over the event that you want to preview, then click the **Preview** button that appears to the right of the event name. 6. An example of the event appears to the right-hand side of the screen. You can use the **Example** toggle button at the top of the example to toggle between the operation result and the entire Signicat event object. :::tip What do the properties in the example mean? To learn what the different properties mean in the examples, see the respective response schema in the [ReuseID API reference](pathname:///apis/reuseid/) documentation. --- ## How it works(Reuseid) Our ReuseID solution is comprised of three key components: - Identity store - Authentication - Identity proofing (optional) These components are fulfilled using different Signicat products, which are combined to create a solution for implementing your own reusable identity. With ReuseID, you always get an **Identity store** and at least one **Authentication** method. These form the base of our ReuseID product. Other Signicat products for **Identity proofing** can be optionally added and orchestrated to fit you needs for a reusable identity. Combining products in ReuseID ## Identity store The identity store component is used to manage all of your end-users and store attributes such as those obtained from a successful identity proofing process. Our identity store is flexible, which means that you can manage or update users in it with our API. Here, you can also add additional user attributes if required. ## Authentication The authentication component is the key to making your ReuseID users reusable. It enables continuous interaction with your end-users and helps to build long-term trust. Once a user is created, their identity can be securely reused for authentication across your entire ecosystem. Use it for the likes of: - Logging in - Signing - Authorising transactions - Recovering to new devices ### Authentication methods ReuseID supports the following authentication methods: - MobileID - Passkeys Both methods are secure and user-friendly; designed to deliver strong, seamless authentication experiences without the need for passwords, OTP codes, or unnecessary friction. #### What is MobileID? MobileID is strong customer authentication product from Signicat that allows you to authenticate your end-users using your mobile app. It offers a rich feature set, strong security, a seamless user experience and full PSD2 compliance. :::tip Our recommendation We recommend that you use this authentication method if you have a mobile app or are pursuing a mobile-first strategy. ::: * [**MobileID authentication**](/docs/mobile-identity/mobileid): Learn more about MobileID in our developer documentation #### What is Passkeys? Passkeys is a modern and passwordless authentication product from Signicat that allow you to authenticate your end-users within a browser. :::tip Our recommendation We recommend that you use this authentication method if you interact primarily with your end-users in a browser and are looking to replace traditional passwords. ::: * [**Passkeys authentication**](/docs/passkeys): Learn more about Passkeys in our developer documentation ### What authentication method should I choose? For guidance on what authentication solution is best for your use case, you can use the table below: | **Question** | **MobileID** | **Passkeys** | | :-- | :-- | :-- | | Do you have a mobile app or mobile strategy? | | | | Do you only need a browser-based solution? | | | | Do you need to be PSD2 SCA compliant? | | | | Do you want omni-channel support? | | | | Do you want one solution for all markets? | | | :::note Want both MobileID and Passkeys? If you want both MobileID and Passkeys, then it is possible for you to combine them and use them in parallel. ::: ## Identity proofing The identity proofing component is important for a reusable identity, as it allows you to: - Verify the identity and collect attributes when creating a new ReuseID user. - Perform a step-up identity verification for existing ReuseID users. - Collect additional information for existing ReuseID users. After a successful identity proofing process, ReuseID adds a set of attributes to the user. These attributes can be returned to you in the response upon a successful authentication. :::note Note The identity proofing component is an optional add-on to ReuseID. You can use one of our pre-defined flows, or we can create a custom flow to fit your requirements. ::: You can easily add identity proofing to your ReuseID by combining it with other Signicat products using one of our orchestration solutions. You can also orchestrate the flow yourself, with or without Signicat products. ReuseID supports three options for conducting an identity proofing: - [Ready-made flows](#ready-made-flows) orchestrated by Signicat. - [Custom flows](#custom-made-flows) orchestrated by Signicat. - [Do-it-yourself flows](#do-it-yourself-flows) orchestrated by you. ### Ready-made flows Our ready-made onboarding flows allow you to quickly roll out a full ReuseID solution, including identity verifications. #### How to implement * [**Mobile flow with eIDV onboarding and MobileID authentication**](/docs/reuseid/identity-proofing/ready-made): Pre-defined onboarding and step-up flows. [//]: # (* [**Web flow with eID**](): Pre-defined onboarding flow using eID and Wallet Hub for identity proofing) ### Custom-made flows If none of the ready-made flows fit your requirements, then we can help you design and build your own custom-made flows. #### How to implement * [**Build your own onboarding and step-up flows**](/docs/reuseid/identity-proofing/custom): Use Signicat orchestration to build ReuseID flows that fits your needs. ### Do-it-yourself flows If you already have an identity proofing process in place, then you can keep that as it is. ReuseID is flexible and allows you to create users and authentication methods without the identity proofing step. You can manage the end-user's identity and set any user attributes at any time using our APIs. ## Learn more To learn more about the individual components that make up ReuseID, see the documentation using the buttons below: * [**Identity store**](/docs/reuseid/identity-store/): Learn more about the identity store for your reusable identity * [**Authentication**](/docs/reuseid/authentication/): Learn more about authentication for your reusable identity * [**Identity proofing**](/docs/reuseid/identity-proofing/): Learn more about identity proofing for your reusable identity --- ## Custom flows You can build your own custom flow for onboarding and step-up for you ReuseID users. When building a custom flow, you can select: - The identity proofing methods - The authentication methods - The orchestration tool ### Identity proofing options In ReuseID custom flows, you can select any of the Signicat identity proofing products that you want to use. You can choose one or combine them: | **Product name** | **Description** | | :-- | :-- | | [ID Document and Biometric Verification](/docs/id-document-and-biometric-verification/) | Scan end-users ID documents and do biometric checks by comparing their ID photo with a selfie or a video recording. | | [eID and Wallet Hub](/docs/eid-hub/) | Use electronic identity (eID) methods, such as Norwegian BankID, FTN or MitID, to verify the end-users identity. | | [Data verification](/docs/data-verification/) | Check, verify and enrich end-users data with trusted data sources. | ### Authentication options ReuseID supports two authentication methods. You can choose one or combine them: | **Product name** | **Description** | | :-- | :-- | | [MobileID](/docs/mobile-identity/mobileid) | MobileID is strong customer authentication product from Signicat that allows you to authenticate your end-users using your mobile app. It offers a rich feature set, strong security, a seamless user experience and full PSD2 compliance. | | [Passkeys](/docs/passkeys) | Passkeys are a modern and passwordless authentication method that allow you to authenticate your end-users within a browser. | ### Orchestration options There are two options for an orchestration engine when considering ready-made flows: | **Product name** | **Description** | | :-- | :-- | | RiskFlow | An orchestration tool that is well-suited for customers who want to own the full end-user journey and have a mobile app. This orchestration engine supports the MobileID authentication method. | | [Mint](/docs/mint/) | A no-code tool for building web orchestrated flows. This orchestration engine supports both MobileID and passkey authentication methods. | ## Get started Once you have selected options for identity proofing, authentication and orchestration you are ready to get started. If using **Mint** as orchestration tool, you can get started by creating your own Mint Flow in the [Signicat Dashboard](https://dashboard.signicat.com/mint). For **RiskFlow**, Signicat will build the flow for you. Reach out to one of our digital identity experts by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard to get started with your custom flow. --- ## Do-it-yourself flows In do-it-yourself flows, you orchestrate the onboarding and step-up flows for ReuseID. In this type of flow you can skip the identity proofing, use your own identity proofing methods, or use any of the Signicat products: | **Product name** | **Description** | | :-- | :-- | | [ID Document and Biometric Verification](/docs/id-document-and-biometric-verification/) | Scan end-users ID documents and do biometric checks by comparing their ID photo with a selfie or a video recording. | | [eID and Wallet Hub](/docs/eid-hub/) | Use electronic identity (eID) methods, such as Norwegian BankID, FTN or MitID, to verify the end-users identity. | | [Data verification](/docs/data-verification/) | Check, verify and enrich end-users data with trusted data sources. | For user management and authentication, you can integrate with the [ReuseID API](/apis/reuseid/). --- ## Identity proofing Choose the identity proofing flow for your reusable identity that best fits your use case. * [**Ready-made flows**](/docs/reuseid/identity-proofing/ready-made/): Learn about identity proofing with ready-made flows orchestrated by Signicat * [**Custom flows**](/docs/reuseid/identity-proofing/custom/): Learn about identity proofing with custom flows orchestrated by Signicat * [**Do-it-yourself flows**](/docs/reuseid/identity-proofing/do-it-yourself/): Learn about identity proofing with do-it-yourself flows orchestrated by you --- ## How it works(Identity-proofing) ## Overview ReuseID combines multiple products from our portfolio to provide you with a solution for implementing your own reusable identity. The first iteration of ReuseID consists of the following components: - **Orchestration**: This is provided by our RiskFlow product. - **Identity proofing**: This is provided by our [ID Document and Biometric Verification](/docs/id-document-and-biometric-verification/) products. - **Identity store**: This is provided by our [MobileID](/docs/mobile-identity/mobileid/) product. Identities are created and stored as MobileID users. - **Authentication**: This is the reusable aspect of ReuseID and is provided by our [MobileID](/docs/mobile-identity/mobileid/) product. With this component, your end-users can perform authentications, authorisations and signatures using your mobile app. Diagram showing overview of components in ReuseID Your end-users use your mobile app to create and use their ReuseID. To do this, you need to integrate our SDK into your app. ReuseID can then orchestrate: - The creation of the user. - The identity proofing process. - Issue of reusable credentials. These steps occur behind the scenes. This means that you have complete control over the design for your end-users. :::note Don't have your own app? If you do not have your own mobile app, it is still possible to use ReuseID. We offer a white-labelled, standalone app that supports ReuseID with the use of VideoID and MobileID. To learn more, see our [Authenticator App](/docs/mobile-identity/mobileid/authenticator-app/) developer documentation. ::: ### How could it look for your end-users? You can use the image slider below to see what the flow could look like for an end-user when they onboard to ReuseID using your app. ## ReuseID components ### Orchestration With ReuseID, you can orchestrate two types of flow: - [Onboarding flow](#about-the-onboarding-flow) - [Step-up flow](#about-the-step-up-flow) Regardless of which flow you use, our ReuseID solution creates a strong binding between the user and its: - Identity proofing processes. - Reusable credentials. - Identity attributes. :::info Need more capabilities? Our ReuseID solution can be extended with additional capabilities. This means that we can support adding more processes to the ReuseID onboarding and step-up if you require them. To do this, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: #### About the onboarding flow The onboarding flow is used to created a new ReuseID. This flow will: - Create a MobileID user. - Register a MobileID device. - Run a VideoID Substantial process for the user. - Add identity attributes to the user. #### About the step-up flow The step-up flow is used to perform step-up identity proofing processes for an existing user. This flow will: - Run a VideoID Substantial process for the user. - Add identity attributes to the user. ### Identity proofing The first iteration of ReuseID supports an identity proofing process of eIDAS Level of Assurance (LoA) 2. This includes our Signicat VideoID service **VideoID Substantial**. In this process: 1. The end-user scans their passport with OCR scanning. 2. A liveness check and comparison to the passport photo is performed. 3. After a successful process, we collect and add the following attributes to the user: - Date of birth - First name - Last name - Gender - Nationality :::note Need more identity attributes? Our ReuseID solution can be extended with additional capabilities, so we can support more identity attributes if you require them. To do this, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: #### Get more identity proofing details There are three identifiers from the identity proofing process performed on a ReuseID that can be used with endpoints in our APIs to obtain more identity proofing information. ##### Identifiers :::CustomTable{columnWidths="25% 75%"} | **Identifier** | **Description** | | :--- | :--- | | `proofingId` | The ID of the identity verification process for the end-user. This is returned as part of the response when you initiate an operation for ReuseID. The identity verification contains the `processId` and `dossierId`. | | `dossierId` | The ID for a [dossier](/docs/id-document-and-biometric-verification/assure-api/key-concepts/#dossier). A dossier is a resource that can contain one or more processes for obtaining identity data. | | `processId` | The ID for a [process](/docs/id-document-and-biometric-verification/assure-api/key-concepts/#process). A process contains identity data obtained in an identity verification process. | ::: ##### Operations - **Fetch all proofings**: To learn how to fetch all proofings for one of your end-users, see the [Get proofings for user](pathname:///apis/mobileid/#tag/User/operation/getProofings) endpoint in our MobileID API reference documentation. - **Manage identity verifications**: To learn how to manage the identity verifications for one of your end-users, see the [Identity verification](pathname:///apis/mobileid/#tag/Identity-verification) API in our MobileID API reference documentation. - **Get full data set**: To learn how to get the full data set for a process, see the [Get process](pathname:///apis/id-document-and-biometric-verification/#tag/Processes/operation/getProcess) endpoint in our ID Document and Biometric Verification: Assure API reference documentation. :::tip Review in the Dashboard You can also review the identity proofing process in the [Signicat Dashboard](https://dashboard.signicat.com/id-document-and-biometric-verification). ::: ### Identity store The identity store component is provided by our MobileID product. It is flexible, which means that you can manage all of your end-users using our API. - To learn how to manage users, see the MobileID [User](pathname:///apis/mobileid/#tag/User) API in our MobileID API reference documentation. - After a successful identity proofing process, ReuseID adds a set of attributes to the user. These attributes can be returned to you in the response upon a successful authentication. :::note Need more user attributes? You can add additional attributes to a user using our MobileID API. To learn how to do this, see the [Update user](pathname:///apis/mobileid/#tag/User/operation/updateUser) endpoint in our MobileID API reference documentation ::: ### Authentication The first iteration of ReuseID leverages MobileID to make the identity reusable. MobileID is our mobile authentication product which allows you to take full control over the end-user experience, and perform compliant multi-factor authentications with either a PIN or biometrics. All end-user authentications, authorisations and signatures are performed within your own mobile app. {/* #### MobileID use cases for ReuseID You can use MobileID in any use case where you need to interact with your end-users. To learn more about what you do, see our [MobileID](/docs/mobile-identity/mobileid/) developer documentation. Some examples of what you can do with MobileID: :::CustomTable{columnWidths="25% 75%"} | **Use case** | **Description** | | :--- | :--- | | Authentication | MobileID can be used when you need to authenticate a user. You can initiate this from any channel such as your app or website. Your end user will always approve the authentication request with your mobile app. | | Authorisation | | | Account recovery | | ::: ## Example implementation Meet XXXX company, who specialise in YYYY. XXXX want to create a reusable identity that will allow them to... With ReuseID, they can... ### End-user flow 1. \*Describe how the end-user starts the process. 2. \*Describe how the end-user onboards. 3. \*Describe how the end-user approaches one of the channels for a transaction. 4. \*Describe how the end-user authenticates or authorises a transaction. 5. \*Describe how the transaction completes. 6. \*Describe any remaining steps/details. ### Sequence diagram Text here. ### Technical flow */} --- ## Ready-made flows To make it as simple as possible for you, we have built ready-made flows that orchestrate the full process for creating the reusable identities. In these flows, we make a strong link between: - The identities - The authentication credentials of the identities - The identity proofing processes You still have control over the end-user journey. Our ready-made flows can be used for ReuseID **Onboarding** or **Step-up**. To learn more, see the sections below. ### About onboarding flows An onboarding flow is used to create a new ReuseID. This flow allows you to: - Create a ReuseID user. - Activate an authentication method for the user. - Run an identity proofing process. - Add identity attributes to the user. ### About step-up flows The step-up flows is used to perform step-up identity proofing processes for an existing user. This flow allows you to: - Authenticate the user. - Run an identity proofing process. - Add identity attributes to the user. ## Discover our ready-made flows * [**Onboard with eIDV and activate MobileID**](/docs/reuseid/identity-proofing/ready-made/onboarding): Learn how to implement ReuseID onboarding in your app * [**Step-up with eIDV and authenticate with MobileID**](/docs/reuseid/identity-proofing/ready-made/step-up): Learn how to implement ReuseID step-up in your app :::tip Want something else? If you did not find a ready-made flow that fits your needs, then we can help you find an appropriate solution. To do this, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Integration prerequisites Before you start, you must complete the following prerequisites: 1. Get access to the VideoID or ReadID, and MobileID SDKs. :::note Contact us to gain access To do this, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: 2. Get started with our MobileID SDKs. To do this, follow the **Getting started** guides for each platform: * [**Getting started (Android SDK)**](/docs/mobile-identity/encap/sdk-android/getting-started/): Lear how to get started with our Android SDK * [**Getting started (iOS SDK)**](/docs/mobile-identity/encap/sdk-ios/getting-started/): Learn how to get started with our iOS SDK 3. Get started with our identity proofing SDK. This process varies depending on which identity proofing provider you select. :::note Contact us to get started To do this, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request more details for your chosen provider. ::: --- ## Integrate ready-made onboarding flows In this ready-made flow guide, you can learn how to implement ReuseID onboarding in your mobile app. ## About ReuseID ready-made onboarding In a ReuseID onboarding flow, there are two required processes that need to be carried out with your app: - A MobileID device registration. - An [identity proofing process](#identity-proofing-process). ### Identity proofing process For the identity proofing process, ReuseID ready-made onboarding supports **ReadID** and **VideoID** as identity proofing providers. This is set using the `provider` parameter in the request body. You can find an overview of the differences between them in the table below: | **Provider name** | **Provider value** | **Description** | | :-- | :-- | :-- | | VideoID | `signicatvideoid` | VideoID is one of Signicat's eIDV services for secure online customer onboarding. It enables you to: Capture a video recording of an ID document and/or the end-user's face. Undertake actions to prove liveness, for example smiling at the camera. | | ReadID | `readid` | ReadID is one of Signicat's eIDV services for secure online customer onboarding. The end-user identifies themselves using ReadID's NFC-supported solution to read their ID document. | :::note Note If you do not set an identity proofing process provider when you start onboarding, then ReuseID uses VideoID by default. ::: ### What does it look like? You can see what a ReuseID onboarding looks like in the sequence diagram below: ```mermaid sequenceDiagram title ReuseID onboarding participant app as Customer app participant mid as MobileID SDK participant vid as VideoID SDK participant server as Customer server participant rid as ReuseID Note over app, rid: ReuseID onboarding app->>server: 1 Onboard new user server->>rid: 2 Start ReuseID onboarding activate rid Note right of rid: 3 Create new user,start MobileID registration,and start identity proofing deactivate rid rid-->>server: 4 Activation code for registration server-->>app: 5 Activation code Note over app, rid: MobileID registration app->>mid: 6 startActivation with Activation code mid->>rid: 7 startActivation rid-->>mid: 8 startActivation response mid-->>app: 9 startActivation response Note over app: Ask for PIN or biometrics app->>mid: 10 finishActivation mid->>rid: 11 finishActivation rid-->>mid: 12 finishActivation response with proofing details mid-->>app: 13 finishActivation response with proofing details Note over app, rid: Perform VideoID app->>server: 14 getAuthorisationToken server-->>app: 15 authorisationToken app->>vid: 16 startVideoID with authorisationToken & proofing details Note over vid, server: User performs VideoID process vid-->>app: 17 VideoID done activate rid Note right of rid: 18 Store proofing process for userUpdate user with identity attributes deactivate rid rid-->>server: 19 ReuseID onboarding completed ``` ## 1. Start onboarding Before your app starts the MobileID registration, your server must start the ReuseID onboarding operation. To do this: 1. Set the `provider` in the request body to choose the identity proofing provider: ```json title="Example: Start onboarding request body" { "externalRef": "000-000-000", "provider": "signicatvideoid", "videoidProviderOptions": { "docTypes": [138, 169, 147, 245, 277], "defaultId": 138 } } ``` ```json title="Example: Start onboarding request body" { "externalRef": "000-000-000", "provider": "readid" } ``` 2. A response is returned to you. This contains the `activationCode` that your app uses to continue the MobileID registration. :::info Want to learn more? To learn more about how the API works, see a complete walkthrough in our ReuseID [Quick start guide](/docs/reuseid/quick-start-guides/identity-proofing/). ::: ## 2. MobileID device registration The next operation that you need to carry out is the MobileID registration. To learn how to implement the registration process for Android and iOS, use the panel buttons below. :::note Terminology for registration When you navigate our documentation, you will also see the term **activation**. In this context, both **activation** and **registration** are synonymous, and refer to the same operation. ::: * [**Android**](/docs/mobile-identity/encap/sdk-android/core-operations/#activation): Learn how to implement the registration process for Android * [**iOS**](/docs/mobile-identity/encap/sdk-ios/core-operations/#activation): Learn how to implement the registration process for iOS ### Operation context Operation context is a MobileID feature that allows you to send data over an end-to-end encrypted channel between the backend and the mobile app. In ReuseID, we use this feature to send data related to the ReuseID operation to the app. :::info Want to learn more? To learn about how the operation context object is structured and how you can fetch the data, see our platform-specific documentation for [Android](/docs/mobile-identity/encap/sdk-android/configure-features/operation-context/) and [iOS](/docs/mobile-identity/encap/sdk-ios/configure-features/operation-context/). ::: :::note Note In the onboarding operation, we only use the post-operation context to share information. ::: #### Post-operation context Once the registration is complete, you will get a `finishActivationResponse` object. This object contains a post-operation context. ##### Response You can find an example of the response below: ```json title="Example: Post-operation context" { "post_operation_context" : { "context_content_b64": , "context_mime": "application/json" } } ``` ##### Response object description You can find a table of descriptions for the response object parameters below: :::CustomTable{columnWidths="25% 75%"} | **Parameter** | **Description** | | :-- | :--- | | `context_content_b64` | The content of the context. In this field, ReuseID will pass a [Signicat operation object](#signicat-operation-object). This object contains information related to the underlying processes. | | `context_mime` | The MIME type of the content. In this field, ReuseID will always return `application/json` for an onboarding scenario. | ::: #### Signicat operation object The Signicat operation object (`signicatOperation`) is used to pass information related to the ReuseID process to the mobile app. ##### Object You can find examples of the object below: ```json title="Example: Signicat operation object for VideoID" { "signicatOperation": { "version": "1", "operation": "registration", "provider": "signicatvideoid", "token": , "url": "https://etrust-sandbox.electronicid.eu/v2", "processType": "substantial", "processId": "8be8325a-9654-4165-a56f-0d1ccdc3bd3e", "videoidProviderOptions": { "docType": 1, "docTypes": [1, 2, 3], "defaultId": 1 } } } ``` ```json title="Example: Signicat operation object for ReadID" { "signicatOperation": { "version": "1", "operation": "registration", "provider": "readid", "token": , "url": "https://saas-preprod.readid.com/odata/v1/ODataServlet", "processType": "sdk", "processId": "8be8325a-9654-4165-a56f-0d1ccdc3bd3e" } } ``` ##### Object description You can find a table of descriptions for the object parameters below: :::CustomTable{columnWidths="25% 75%"} | **Parameter** | **Description** | | :-- | :-- | | `version` | The version of the `signicatOperation` object. | | `operation` | The type of MobileID operation. For ReuseID onboarding operations, this will be `registration`. | | `provider` | The ID document and biometric verification provider. For ready-made flows, this is `signicatvideoid` or `readid`. | | `token` | The token/secret to be used for starting the ID document and biometric verification process. | | `url` | The URL to be used for starting the ID document and biometric verification process. | | `processType` | The type of ID document and biometric verification process. | | `processId` | The ID document and biometric verification process ID. | | `videoidProviderOptions` | Returned only when `provider` is `signicatvideoid`. This object contains VideoID provider-specific configuration options. | ::: #### VideoID provider options object The VideoID provider options object (`videoidProviderOptions`) contains VideoID provider-specific configuration options. You can find a table of descriptions for the object parameters below: ##### Object description :::CustomTable{columnWidths="25% 50% 25%"} | **Parameter** | **Description** | **Allowed values** | | :-- | :-- | :-- | | `docType` | Specify a country and eID when starting the VideoID process from the SDK.

If a document type is specified, then the VideoID wizard will not be shown, and VideoID process will be triggered for that document. | Integer, from the IDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | | `docTypes` | Specify countries and eIDs when starting the VideoID process from the SDK.

If document types are specified, then the VideoID wizard will be shown with a list of the specified ID documents that the end-user can select from. | Array of integers, from the IDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | | `defaultId` | Allows you to specify a default country for the selector in the VideoID wizard. The end-user can still select another option from the selector if available.

**Note**: Can only be used if values are set for `docTypes`. | Integer, from the eIDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | ::: ## 3. Perform identity proofing Once you have completed the MobileID registration, start the identity proofing process that matches the `provider` in the [Signicat operation object](#signicat-operation-object). - For **VideoID**, see the [VideoID as provider](#videoid-as-provider) section. - For **ReadID**, see the [ReadID as provider](#readid-as-provider) section. ### VideoID as provider If the `provider` is `signicatvideoid`, then you need to start the VideoID process in your app. To do this: #### 1. VideoID authorisation Before starting the VideoID activity, you need to get an authorisation token for VideoID. You can do this by making a request to the `videoid.request` API: 1. Obtain the following parameters from the [Signicat operation object](#signicat-operation-object): - `url` - `token` 2. Input this data into the following example: ```bash title="Example: Request to get VideoID authorisation token" curl -X POST /videoid.request \ -H 'Authorization: Bearer ' \ -H 'content-type: application/json' \ -d '{ "process": "Unattended" }' ``` :::info What does unattended mean? In the SDK, the process that you are starting for VideoID is called `Unattended`. In other parts of the documentation, you will see us refer to this operation as `Substantial`. ::: 3. After a successful request , you will receive the following response: ```json title="Example: Response with VideoID authorisation token" { "id": "87a819bd-9419-417a-9e55-cab8789d4115", "authorization": "" } ``` :::note Note The `authorization` from this request is required in the next step when you start a VideoID activity. ::: #### 2. Start VideoID activity Next, you need to start the VideoID activity in your app. You should consider the following when starting the activity: :::CustomTable{columnWidths="25% 75%"} | **Considerations** | **Description** | | :-- | :-- | | **Environment** | This is the environment used for VideoID.
  • The URL to use is returned in [Signicat operation object](#signicat-operation-object).
  • The authorisation token is returned in the [VideoID request](#1-videoid-authorisation).
| | **ID document configuration** | When launching the VideoID activity, you can pass configurations for what document to show or use during the process.

In the [Signicat operation object](#signicat-operation-object), you will receive an [eID provider options object](#eid-provider-options-object).

This object can contain `docType`, `docTypes` and `defaultId`, if they were set at the start of the ReuseID operation. | ::: #### Code examples ```swift title="Swift example" func makeUIViewController(context: Context) -> VideoIDSDK.VideoIDSDKViewController { let environment: VideoIDSDK.SDKEnvironment = VideoIDSDK.SDKEnvironment( url: <>, authorization: <> ) let viewController = VideoIDSDKViewController( environment: environment, docType: <>, docTypes: <>, idDefault: <>, ) viewController.delegate = self return viewController } // Error Handling func onComplete(videoID: String) { // VideoID process succeeded - Handle the next steps here } func onError(_ error: VideoIDError) { // VideoID process failed - Handle the error here } ``` ```kotlin title="Kotlin example" val startForResult: ActivityResultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result -> when (result.resultCode) { Activity.RESULT_OK -> { // VideoID scan successful, continue app flow } Activity.RESULT_CANCELED -> { // VideoID failure, handle the error result.data?.run { val errorId = getStringExtra(VideoIdServiceActivity.RESULT_ERROR_CODE) val errorMsg = getStringExtra(VideoIdServiceActivity.RESULT_ERROR_MESSAGE) } } } } private fun launchVideoIdActivity( url: String, authToken: String, defaultId: Int? = null, docType: Int? = null, docTypes: IntArray? = null){ startForResult.launch(Intent(this, VideoIDActivity::class.java).apply { putExtra(VideoIDActivity.ENVIRONMENT, Environment(URL(url), authToken)) defaultId?.let { putExtra(VideoIDActivity.ID_DEFAULT, it) } docType?.let { putExtra(VideoIDActivity.ID_DOCUMENT, it) } docTypes?.let { putExtra(VideoIDActivity.IDS_DOCUMENT, it) } }) } ``` :::info Want to customise VideoID further? To learn more about VideoID and the available customisation options, you can navigate to the SDK documentation available in the [ElectronicID dashboard](https://etrust-sandbox.electronicid.eu/dashboard3). ::: ### ReadID as provider If the `provider` is `readid`, then you need to start the ReadID NFC scanning flow with the ReadID SDK. The selected ReadID process is created by ReuseID, and your app should use the values returned in the [Signicat operation object](#signicat-operation-object) when continuing from MobileID registration to identity proofing. When following the ReadID guide, map the ReuseID values to the ReadID SDK values as shown in the table below: :::CustomTable{columnWidths="25% 35% 40%"} | **ReadID guide value** | **ReuseID value** | **Description** | | :-- | :-- | :-- | | `providerApiUrl` / `baseUrl` | `signicatOperation.url` | Use this as the ReadID SDK base URL. For Android, pass it to `setBaseURL`. For iOS, set `configuration.baseUrl`. | | `authorization` / OAuth token | `signicatOperation.token` | Use this as the ReadID SDK authorisation token. For Android, pass it to `setOAuthToken`. For iOS, set `configuration.oauthToken`. | | `processId` / opaque ID | `signicatOperation.processId` | Use this as the ReadID SDK opaque ID. For Android, pass it to `setOpaqueID`. For iOS, set `configuration.opaqueId`. | ::: All values in this table are available in the [Signicat operation object](#signicat-operation-object). :::info Want to learn more? For platform-specific SDK setup and code examples, see the [ReadID SaaS SDK integration guide](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-readid/integration-guide-readid/). ::: --- ## Integrate ready-made step-up flows In this ready-made flow guide, you can learn how to implement ReuseID step-up in your mobile app. ## About ReuseID step-up In a ReuseID step-up flow, there are two required processes that need to be carried out with your app: - A MobileID device authentication. - An [identity proofing process](#identity-proofing-process). ### Identity proofing process For the identity proofing process, ReuseID ready-made step-up supports **ReadID** and **VideoID** as identity proofing providers. This is set using the `provider` parameter in the request body. You can find an overview of the differences between them in the table below: | **Provider name** | **Provider value** | **Description** | | :-- | :-- | :-- | | VideoID | `signicatvideoid` | VideoID is one of Signicat's eIDV services for secure online customer onboarding. It enables you to: Capture a video recording of an ID document and/or the end-user's face. Undertake actions to prove liveness, for example smiling at the camera. | | ReadID | `readid` | ReadID is one of Signicat's eIDV services for secure online customer onboarding. The end-user identifies themselves using ReadID's NFC-supported solution to read their ID document. | :::note Note If you do not set an identity proofing process provider when you start step-up, then ReuseID uses VideoID by default. ::: ### What does it look like? You can see what a ReuseID step-up looks like in the sequence diagram below: ```mermaid sequenceDiagram title ReuseID step-up participant app as Customer app participant mid as MobileID SDK participant vid as VideoID SDK participant server as Customer server participant rid as ReuseID server->>rid: 1 Start ReuseID step-up for user activate rid Note right of rid: 2 Start MobileID authentication and start identity proofing deactivate rid rid-->>server: 3 Step-up started Note over app, rid: MobileID authentication server-->>app: 4 Push notification app->>mid: 5 startAuthentication mid->>rid: 6 startAuthentication rid-->>mid: 7 startAuthentication response with proofing details mid-->>app: 8 startAuthentication response with proofing details app->>mid: 9 finishAuthentication mid->>rid: 10 finishAuthentication rid-->>mid: 11 finishAuthentication response with proofing details mid-->>app: 12 finishAuthentication response with proofing details Note over app, rid: Perform VideoID app->>server: 13 getAuthorisationToken server-->>app: 14 authorisationToken app->>vid: 15 startVideoID with authorisationToken & proofing details Note over vid, server: User performs VideoID process vid-->>app: 16 VideoID done activate rid Note right of rid: 17 Store proofing process for user and update user with identity attributes deactivate rid rid-->>server: 18 ReuseID onboarding completed ``` ## 1. Start step-up Before your app starts the MobileID registration, your server must start the ReuseID step-up operation. To do this, set the `provider` in the request body to choose the identity proofing provider: ```json title="Example: Start step-up request body" { "userId": "a1e26081-35b4-4557-a46a-ef50bc91672f", "deviceId": "b1g73121-55c4-9238-l39j-ek60dc91872g", "provider": "signicatvideoid", "videoidProviderOptions": { "docTypes": [138, 169, 147, 245, 277], "defaultId": 138 } } ``` ```json title="Example: Start step-up request body" { "userId": "a1e26081-35b4-4557-a46a-ef50bc91672f", "deviceId": "b1g73121-55c4-9238-l39j-ek60dc91872g", "provider": "readid" } ``` :::info Want to learn more? To learn more about how the API works, see a complete walkthrough in our ReuseID [Quick start guide](/docs/reuseid/quick-start-guides/identity-proofing/). ::: ## 2. MobileID authentication The next operation that you need to carry out is the MobileID authentication. To learn how to implement the registration process for Android and iOS, use the panel buttons below. * [**Android**](/docs/mobile-identity/encap/sdk-android/core-operations/#authentication): Learn how to implement the authentication for Android * [**iOS**](/docs/mobile-identity/encap/sdk-ios/core-operations/#authentication): Learn how to implement the authentication for iOS. ### Operation context Operation context is a MobileID feature that allows you to send data over an end-to-end encrypted channel between the backend and the mobile app. In ReuseID, we use this feature to send data related to the ReuseID operation to the app. :::info Want to learn more? To learn about how the operation context object is structured and how you can fetch the data, see our platform-specific documentation for [Android](/docs/mobile-identity/encap/sdk-android/configure-features/operation-context/) and [iOS](/docs/mobile-identity/encap/sdk-ios/configure-features/operation-context/). ::: :::note Note In the step-up operation, we use both the pre-operation and post-operation context to share information. ::: #### Pre-operation context After the `startAuthentication` request, you will get a `startAuthenticationResult` object. This object contains a pre-operation context. ##### Response You can find an example of the response below: ```json title="Example: Pre-operation context" { "pre_operation_context" : { "context_content_b64": , "context_mime": "application/json" } } ``` ##### Response object description You can find a table of descriptions for the response object parameters below: :::CustomTable{columnWidths="25% 75%"} | **Parameter** | **Description** | | :-- | :--- | | `context_content_b64` | The content of the context. In this field, ReuseID will pass a [Signicat operation object](#signicat-operation-object). For the pre-operation context, this object will only contain the `operation`, `provider` and `processType`. | | `context_mime` | The MIME type of the content. In this field, ReuseID will always return `application/json` for a step-up scenario. | ::: :::info Using the pre-operation context content This parameter can be helpful for designing the end-user flow. For example, the `operation` parameter can be used to know that this is a ReuseID step-up operation and not a normal MobileID authentication. ::: #### Post-operation context Once the authentication is complete, you will get a `finishAuthenticationResult` object. This object contains a post-operation context. ##### Response You can find an example of the response below: ```json title="Example: Post-operation context" { "post_operation_context" : { "context_content_b64": , "context_mime": "application/json" } } ``` ##### Response object description You can find a table of descriptions for the response object parameters below: :::CustomTable{columnWidths="25% 75%"} | **Parameter** | **Description** | | :-- | :--- | | `context_content_b64` | The content of the context. In this field, ReuseID will pass a [Signicat operation object](#signicat-operation-object). This object contains information related to the underlying processes. | | `context_mime` | The MIME type of the content. In this field, ReuseID will always return `application/json` for a step-up scenario. | ::: #### Signicat operation object The Signicat operation object (`signicatOperation`) is used to pass information related to the ReuseID process to the mobile app. ##### Object You can find examples of the object below: ```json title="Example: Signicat operation object for VideoID" { "signicatOperation": { "version": "1", "operation": "authentication", "provider": "signicatvideoid", "token": , "url": "https://etrust-sandbox.electronicid.eu/v2", "processType": "substantial", "processId": "0dca14cf-957d-46d9-b374-520f9c650859", "videoidProviderOptions": { "docType": 1, "docTypes": [1, 2, 3], "defaultId": 1 } } } ``` ```json title="Example: Signicat operation object for ReadID" { "signicatOperation": { "version": "1", "operation": "authentication", "provider": "readid", "token": , "url": "https://saas-preprod.readid.com/odata/v1/ODataServlet", "processType": "sdk", "processId": "0dca14cf-957d-46d9-b374-520f9c650859" } } ``` ##### Object description You can find a table of descriptions for the object parameters below: :::CustomTable{columnWidths="25% 75%"} | **Parameter** | **Description** | | :-- | :-- | | `version` | The version of the `signicatOperation` object. | | `operation` | The type of MobileID operation. For ReuseID step-up operations, this will be `authentication`. | | `provider` | The ID document and biometric verification provider. For ready-made flows, this is `signicatvideoid` or `readid`. | | `token` | The token/secret to be used for starting the ID document and biometric verification process. | | `url` | The URL to be used for starting the ID document and biometric verification process. | | `processType` | The type of ID document and biometric verification process. | | `processId` | The ID document and biometric verification process ID. | | `videoidProviderOptions` | Returned only when `provider` is `signicatvideoid`. This object contains VideoID provider-specific configuration options. | ::: #### VideoID provider options object The VideoID provider options object (`videoidProviderOptions`) contains VideoID provider-specific configuration options. You can find a table of descriptions for the object parameters below: :::CustomTable{columnWidths="25% 50% 25%"} | **Parameter** | **Description** | **Allowed values** | | :-- | :-- | :-- | | `docType` | Specify a country and eID when starting the VideoID process from the SDK.

If a document type is specified, then the VideoID wizard will not be shown, and VideoID process will be triggered for that document. | Integer, from the IDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | | `docTypes` | Specify countries and eIDs when starting the VideoID process from the SDK.

If document types are specified, then the VideoID wizard will be shown with a list of the specified ID documents that the end-user can select from. | Array of integers, from the IDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | | `defaultId` | Allows you to specify a default country for the selector in the VideoID wizard. The end-user can still select another option from the selector if available.

**Note**: Can only be used if values are set for `docTypes`. | Integer, from the eIDs in the [document list](https://etrust-live.electronicid.eu/v2/videoid.idtypes). | ::: ## 3. Perform identity proofing Once you have completed the MobileID authentication, start the identity proofing process that matches the `provider` in the [Signicat operation object](#signicat-operation-object). - For **VideoID**, see the [VideoID as provider](#videoid-as-provider) section. - For **ReadID**, see the [ReadID as provider](#readid-as-provider) section. ### VideoID as provider If the `provider` is `signicatvideoid`, then you need to start the VideoID process in your app. To do this: #### 1. VideoID authorisation Before starting the VideoID activity, you need to get an authorisation token for VideoID. You can do this by making a request to the `videoid.request` API: 1. Obtain the following parameters from the [Signicat operation object](#signicat-operation-object): - `url` - `token` 2. Input this data into the following example: ```bash title="Example: Request to get VideoID authorisation token" curl -X POST /videoid.request \ -H 'Authorization: Bearer ' \ -H 'content-type: application/json' \ -d '{ "process": "Unattended" }' ``` :::info What does `Unattended` mean? In the SDK, the process that you are starting for VideoID is called `Unattended`. In other parts of the documentation, you will see us refer to this operation as `Substantial`. ::: 3. After a successful request , you will receive the following response: ```json title="Example: Response with VideoID authorisation token" { "id": "87a819bd-9419-417a-9e55-cab8789d4115", "authorization": "" } ``` :::note Note The `authorization` from this request is required in the next step when you start a VideoID activity. ::: #### 2. Start VideoID activity Next, you need to start the VideoID activity in your app. You should consider the following when starting the activity: :::CustomTable{columnWidths="25% 75%"} | **Considerations** | **Description** | | :-- | :-- | | **Environment** | This is the environment used for VideoID.
  • The URL to use is returned in [Signicat operation object](#signicat-operation-object).
  • The authorisation token is returned in the [VideoID request](#1-videoid-authorisation).
| | **ID document configuration** | When launching the VideoID activity, you can pass configurations for what document to show or use during the process.

In the [Signicat operation object](#signicat-operation-object), you will receive an [eID provider options object](#eid-provider-options-object).

This object can contain `docType`, `docTypes` and `defaultId`, if they were set at the start of the ReuseID operation. | ::: #### Code examples ```swift title="Swift example" func makeUIViewController(context: Context) -> VideoIDSDK.VideoIDSDKViewController { let environment: VideoIDSDK.SDKEnvironment = VideoIDSDK.SDKEnvironment( url: <>, authorization: <> ) let viewController = VideoIDSDKViewController( environment: environment, docType: <>, docTypes: <>, idDefault: <>, ) viewController.delegate = self return viewController } // Error Handling func onComplete(videoID: String) { // VideoID process succeeded - Handle the next steps here } func onError(_ error: VideoIDError) { // VideoID process failed - Handle the error here } ``` ```kotlin title="Kotlin example" val startForResult: ActivityResultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result -> when (result.resultCode) { Activity.RESULT_OK -> { // VideoID scan successful, continue app flow } Activity.RESULT_CANCELED -> { // VideoID failure, handle the error result.data?.run { val errorId = getStringExtra(VideoIdServiceActivity.RESULT_ERROR_CODE) val errorMsg = getStringExtra(VideoIdServiceActivity.RESULT_ERROR_MESSAGE) } } } } private fun launchVideoIdActivity( url: String, authToken: String, defaultId: Int? = null, docType: Int? = null, docTypes: IntArray? = null){ startForResult.launch(Intent(this, VideoIDActivity::class.java).apply { putExtra(VideoIDActivity.ENVIRONMENT, Environment(URL(url), authToken)) defaultId?.let { putExtra(VideoIDActivity.ID_DEFAULT, it) } docType?.let { putExtra(VideoIDActivity.ID_DOCUMENT, it) } docTypes?.let { putExtra(VideoIDActivity.IDS_DOCUMENT, it) } }) } ``` :::info Want to customise VideoID further? To learn more about VideoID and the available customisation options, you can navigate to the SDK documentation available in the [ElectronicID dashboard](https://etrust-sandbox.electronicid.eu/dashboard3). ::: ### ReadID as provider If the `provider` is `readid`, then you need to start the ReadID NFC scanning flow with the ReadID SDK. The selected ReadID process is created by ReuseID, and your app should use the values returned in the [Signicat operation object](#signicat-operation-object) when continuing from MobileID authentication to identity proofing. When following the ReadID guide, map the ReuseID values to the ReadID SDK values as shown in the table below: :::CustomTable{columnWidths="25% 35% 40%"} | **ReadID guide value** | **ReuseID value** | **Description** | | :-- | :-- | :-- | | `providerApiUrl` / `baseUrl` | `signicatOperation.url` | Use this as the ReadID SDK base URL. For Android, pass it to `setBaseURL`. For iOS, set `configuration.baseUrl`. | | `authorization` / OAuth token | `signicatOperation.token` | Use this as the ReadID SDK authorisation token. For Android, pass it to `setOAuthToken`. For iOS, set `configuration.oauthToken`. | | `processId` / opaque ID | `signicatOperation.processId` | Use this as the ReadID SDK opaque ID. For Android, pass it to `setOpaqueID`. For iOS, set `configuration.opaqueId`. | ::: All values in this table are available in the [Signicat operation object](#signicat-operation-object). :::info Want to learn more? For platform-specific SDK setup and code examples, see the [ReadID SaaS SDK integration guide](/docs/id-document-and-biometric-verification/provider-specific-integrations/signicat-readid/integration-guide-readid/). ::: --- ## Identity store The ReuseID identity store is the central repository for managing ReuseID users, their associated attributes, and their authentication methods. It allows you to build a reusable identity for each of your end-users by linking their devices, credentials, and attributes together. ## ReuseID user At the core of the identity store is the **ReuseID user**. Each ReuseID user represents an end-user entity. ### Authentication methods Each ReuseID user can be associated with multiple authentication methods, including **MobileID** and **Passkeys**: * [**MobileID**](/docs/mobile-identity/mobileid): Learn more about MobileID authentication * [**Passkeys**](/docs/passkeys): Learn more about Passkeys authentication The ReuseID user can also register multiple instances of each authentication method, for example: - They could have multiple passkeys registered, such as one on a smartphone and one on a laptop. - They could have multiple MobileID devices registered, such as a primary mobile phone and a backup tablet. This flexibility allows your end-users to securely authenticate across all of their devices using either MobileID, Passkeys, or a combination of both. ### User attributes You can enrich a ReuseID user by attaching **User attributes**. Attributes are key-value pairs that contain information about the end-user. These attributes can include: - **Personally Identifiable Information (PII)**: For example, an end-user's first name, last name, date of birth, or email address. - **Customer-specific properties**: For example, roles, permission groups, or membership tiers. :::note Note ReuseID user attributes are optional, which means that it is your choice whether you add any and what they are. ::: ```json title="Example: Create user request (set attributes)" { "attributes": { "firstname": "Jane", "lastname": "Doe", "member-tier": "diamond", "role": "admin" } } ``` #### Returning user attributes When an authentication transaction is completed, you can request that these user attributes are included in the transaction response by using the `requestedUserAttributes` property inside `operationProperties`. This allows your application to seamlessly receive up-to-date user information such as their access level or display name immediately upon successful authentication, simplifying your authorisation logic. To learn how you can request and receive attributes for MobileID and Passkeys authentications, see the examples below: ```json title="Example: Authentication request (request attributes)" { "operationProperties": { "requestedUserAttributes": ["firstname", "lastname", "member-tier"] } // ... Other request data. } ``` ```json title="Example: Authentication response (request attributes)" { "transactionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "state": "COMPLETED", "operationProperties": { "requestedUserAttributes": { "firstname": "Jane", "lastname": "Doe", "member-tier": "diamond" } }, // ... Other response data. } ``` ### External reference To map a ReuseID user to a user profile in your own system's database, you can use the **External Reference** property. This allows you to quickly look up and correlate the ReuseID user with your own backend records. For example, if your internal user ID is `customer-12345`, then you can set the `externalRef` to this value when creating or updating the ReuseID user. ```json title="Example: Create user request (set external reference)" { "externalRef": "customer-12345", } ``` ### User segment The **User Segment** property allows you to group users based on specific criteria or requirements. This enables you to manage different user groups within the same account, enabling more granular management and reporting. For example, you could create segments to group users by: - User type, such as `b2c-customers` and `b2b-partners`. - Country, such as `NO`, `SE`, `DE`. ```json title="Example: Create user request (set segment)" { "segment": "SE", } ``` ## User management operations You can manage all aspects of the ReuseID identity store programmatically using the ReuseID REST API. For example, you can carry out operations such as: - Creating users - Updating attributes - Managing users * [**ReuseID API**](/docs/reuseid/api-reference): Explore endpoints and properties in the ReuseID API reference ### Locking a user If you detect suspicious activity or need to temporarily disable an end-user's access, you can lock a ReuseID user. To do this, you can use the [**Update user**](pathname:///apis/reuseid/#tag/User/operation/updateUser) endpoint to set the ReuseID user's state to `LOCKED`. :::note Note This blocks all authentication attempts across all of their registered methods (both Passkeys and MobileID), until they are unlocked by an administrator. ::: ### Resolving external references If you want to use your own identifier for the ReuseID user, then you can map the value to the `externalRef` property. To then find the ReuseID user, you can use the [**Resolve user by external reference**](pathname:///apis/reuseid/#tag/User/operation/resolveUserIDByExtref) endpoint to resolve your internal identifier. :::tip Tip This allows you to find the internal Signicat `userId` without having to store it locally, facilitating operations such as updating the user's attributes or initiating new authentications. ::: ### Getting user credentials To retrieve a complete list of all authentication methods (credentials) that have been registered for a specific ReuseID user, you can use the [**Get credentials for user**](pathname:///apis/reuseid/#tag/User/operation/getCredentials) endpoint. :::note Note This includes all active Passkeys and MobileID devices. ::: ### Getting user transactions To retrieve a complete historical list of all operations, for example authentication and registration transactions that have been performed by a specific ReuseID user, you can use the [**Get transactions for user**](pathname:///apis/reuseid/#tag/User/operation/getUserTransactions) endpoint. :::tip Tip You can use this operation to audit user activity, detect anomalies, or display a recent login history to the end-user. ::: --- ## ReuseID Signicat ReuseID lets you create, manage, and authenticate your end-users securely across your entire digital ecosystem. ## About ReuseID - It is designed to be flexible and compliant. - It allows you to authenticate using modern methods supported in mobile apps and on websites, without compromising on user experience. - You only need to create a user once. - There is no repeated KYC or unnecessary friction. - You can reuse that trusted identity securely whenever needed: - Across all services, channels, and markets. - Across all operations, such as onboarding, login, authorisation, or signing. ## Get started * [**Try it out**](/docs/reuseid/quick-start-guides/try-it-out): Learn how to test out a ReuseID using the Signicat Dashboard * [**Quick start guides**](/docs/reuseid/quick-start-guides/): Learn how to test out ReuseID using our ReuseID APIs * [**How it works**](/docs/reuseid/how-it-works): Learn about how ReuseID works * [**API reference**](/docs/reuseid/api-reference): Explore endpoints and properties with example requests and responses ## Releases and upgrades * [**Release notes**](/docs/reuseid/release-notes/): View ReuseID release notes ## Support * [**Error codes**](/docs/reuseid/error-codes): View the error codes for ReuseID * [**Best practices**](/docs/reuseid/best-practices/): Learn about best practices when implementing ReuseID --- ## Quick start guide(6) # Quick start guide Learn how to test out a ReuseID onboarding or step-up flow using the Authenticator App and the ReuseID API. This quick start guide shows you how to: 1. Perform a ReuseID onboarding or step-up flow. 2. Review the identity proofing process. 3. Reuse the ReuseID. 4. Manage the users. :::info Want to try ReuseID without making API requests? This guide requires that you make API requests using a tool of your choice. If you want to try out ReuseID without making API requests, then you can use the [Try it out](https://dashboard.signicat.com/reuseid/try-it-out) page in the Signicat Dashboard. Here, you can use a button to trigger ReuseID operations instead. ::: ## Prerequisites ### 1. Connect to the ReuseID API Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). :::note What permissions are required? Ensure that you set the following permissions for your API client: - **ReuseID Onboarding API** - **ReuseID MobileID Device API** ::: ### 2. Add MobileID to your account To use MobileID as the authentication method in ReuseID you need to add the product to your account. To do this: 1. Go to **Signicat Dashboard** > **Products** > [**MobileID**](https://dashboard.signicat.com/mobileid/). 2. Click the **+ Add MobileID** button. ## Set it up Next, you have to set up a tool for triggering operations and access our Authenticator App to perform them. ### 1. Set up Postman :::note Using other tools This guide provides steps for using [Postman](https://www.postman.com/downloads) as a tool for initiating the APIs, however, you can use the preferred tool of your choice. ::: To set up ReuseID ready-made onboarding API in Postman and obtain an access token: 1. Open Postman. 2. Import the collection. To do this: 1. Navigate to the **Collections** tab on the left-hand side of the screen, then click the **Import** button. Screenshot showing import of ReuseID Onboarding collection into Postman 2. In the blank field in the dialogue box, paste the URL to our ReuseID Onboarding API specification :::tip Our recommendation We recommend that you generate the request and response parameters from the examples in the schema, and that you create folders according to the tags. To do this: 1. Click the **View import settings** button. 2. In the **Parameter generation** section, select **Example** from the dropdown menu. 3. In the **Folder organization** section, select **Tags** from the dropdown menu. ::: 3. Click the **Import** button in the dialogue box to finalise the import. 3. Create variables. To do this, click the **Variables** tab, and add the following: :::CustomTable{columnWidths="25% 75%"} | **Variable** | **Value** | | :-- | :-- | | `baseUrl` | This variable becomes present after import. Make sure that the value is `https://api.signicat.com/`. | | `authClientID` | The client ID that you obtained when you created the API client. | | `authClientSecret` | The client secret that you obtained when you created the API client. | ::: Screenshot showing creation of variables in Postman 4. Set up authorisation. To do this, go to the **Authorization** tab and update the following: :::CustomTable{columnWidths="25% 75%"} | **Name** | **Value** | | :-- | :-- | | Type | `OAuth 2.0` | | Grant type | `Client Credentials` | | Access Token URL | `https://api.signicat.com/auth/open/connect/token` | | Client ID | `{{authClientID}}` | | Client Secret | `{{authClientSecret}}` | | Scope | `signicat-api` | ::: Screenshot showing set up of authorisation in Postman 5. Click on the **Get new access token** button to get an access token. 6. To add the token to the requests, click **Proceed**, then **Use Token**. 7. Save your changes. :::tip Auto-refresh your access token To automatically refresh your access token after it has expired, enable the **Auto-refresh token** toggle button under the **Authorization** tab. You can only enable auto-refresh tokens after you have received your first valid token. ::: :::note Success! You have now set up Postman for the ReuseID ready-made Onboarding APIs. ::: ### 2. Install our Authenticator App The Authenticator App is our white-label mobile application which enables you to perform operations on a mobile device, so that you can start testing out ReuseID as quickly as possible. :::details Want to use our SDK instead? It is also possible to use our SDK and integrate it into your own app instead. To get access to the SDK, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: #### iOS To install our Authenticator App on your iPhone, you have to: 1. Scan the QR code below on your mobile device: QR code to install the iOS Authenticator App 2. Install the latest version. #### Android To install our Authenticator App on your Android, you have to: 1. Scan the QR code below on your mobile device: QR code to install the Android Authenticator App 2. Install the latest version. ### 3. Configure our Authenticator App Once you have installed the Authenticator App, you need to configure it to use your account. To do this, you need to update the following values: - Application ID (`applicationId`) - Public E2E key (`publicKey`) - Server URL (`https://api.signicat.com/encore/encap`) :::note Note Our server URL is the same for both sandbox and production accounts. ::: #### How to obtain these values To get your application ID (`applicationId`) and public E2E key (`publicKey`), you need to: 1. Go to **Signicat Dashboard** > **Products** > **MobileID** > [**Details**](https://dashboard.signicat.com/mobileid/details). 2. Click on **Quick configuration** in the top-right corner. :::note Manually add values If you do not wish to use the QR code scanner, then you can also find the **Application ID** value under the **Account tab**, and the **Public key** value under the **E2E keys** tab. ::: #### How to set these values :::note Other options It is also possible to select a configuration from the dropdown list, or manually add your own configuration by clicking `+`. ::: ## Try onboarding with eIDV and MobileID authentication You have now completed all required preparations and are ready to perform ReuseID operations In this guide you'll learn how to use ReuseID ready-made flows which performs identity proofing with an eIDV and authenticates with MobileID. - [Onboarding flow](#ready-made-reuseid-onboarding) - Creates a ReuseID user. - Activates a MobileID device. - Performs identity proofing process. - Creates a strong binding between the ReuseID user and the identity proofing process. - Adds identity attributes to the ReuseID user. - [Step-up flow](#ready-made-reuseid-step-up) - Performs a MobileID device authentication. - Performs an identity proofing process. - Creates a strong binding between the ReuseID user and the identity proofing process. - Adds identity attributes to the ReuseID user. ### Ready-made ReuseID onboarding 1. In Postman, navigate to Signicat ReuseID Onboarding API reference > **Onboarding** > **Start onboarding**. 2. Under the **Body** tab, you can input your own request body. This API will default to `signicatvideoid` as provider if not specified in the request. ```json title="Example: ReuseID onboarding request body" { "externalRef": "000-000-000", "provider" : "signicatvideoid", "videoidProviderOptions" : { "docTypes" : [138,169,147,245,277], "defaultId" : 138 } } ``` ```json title="Example: ReuseID onboarding request body" { "provider" : "readid" } ``` 3. Click the **Send** button. 4. You have now started a registration operation. The response contains an `activationCode`, which you need in the next step. :::details Show activation code as QR code in Postman To get the best the user experience, Postman can show the activation code as a QR code. This means that you do not have to manually type the code in the Authenticator App. To do this, add the following snippet to **Script** > **Post-response** in the `POST` request: ``` let response = pm.response.json(); let qrcTemplate = ''; pm.visualizer.set(qrcTemplate, {}); ``` ::: ```json title="Example: Start ReuseID onboarding response" { "data": { "status": "Pending", "transactionId": "94099e7e-b391-45fb-9404-b54682f16d03", "userId": "7f1994f0-5fed-4e0f-a8e2-64da520a09cb", "activationCode": "2005468691", "dossierId": "41ff5755-4ece-42cf-b7de-3efd0181ba88", "processId": "8be8325a-9654-4165-a56f-0d1ccdc3bd3e" } } ``` 5. Open the Authenticator App. 6. Click on the button to start the onboarding on the device. 7. Scan or enter the `activationCode` that was obtained in **Step 4**. :::note Note The activation code is only valid until the session expiry time (`sessionExpiryTime`). ::: 8. Select a PIN. 9. Select if you want to activate biometrics. 10. Follow the instructions for the identity proofing process. 11. Once you completed the identity proofing process in the Authenticator app go back to Postman. 12. In Postman, navigate to **Onboarding** > **Get onboarding**. 13. Under the **Params** tab, update the value of `transactionId` to the value you obtained in the **Start onboarding** response. 14. Click the **Send** button. ```json title="Example: Get result of ReuseID onboarding response" { "data": { "transactionId": "e35ebbf7-9631-4966-9762-ae939c80eda1", "userId": "a1e26081-35b4-4557-a46a-ef50bc91672f", "activationCode": "8954685641", "deviceId": "b1g73121-55c4-9238-l39j-ek60dc91872g", "proofingId": "30745db7-4403-4403-aa7e-cb35435ee565", "dossierId": "3d563ac4-9d26-4a6a-b58d-5a29cacfe015", "processId": "2f54b0a4-1a77-42e2-98d8-369116ef2055", "status": "Completed", "userData": { "firstName": "JANE", "lastName": "SMITH", "dateOfBirth": "1990-01-01", "gender": "F", "nationality": "NOR" } } } ``` :::note Success! You have now completed a ready-made flow for onboarding to ReuseID with eIDV and setup credentials for MobileID. ::: :::details What does it look like in the Authenticator App? ::: ### Ready-made ReuseID step-up 1. In Postman, navigate to Signicat ReuseID Onboarding API reference > **Step-up** > **Start step-up**. 2. Under the **Body** tab, you can input your own request body. For this API, it is required to set both the user ID (`userId`) and the device ID (`deviceId`). These are the IDs of the ReuseID user and MobileID device. This API will default to `signicatvideoid` as provider if not specified in the request. ```json title="Example: ReuseID step-up request body" { "userId": "a1e26081-35b4-4557-a46a-ef50bc91672f", "deviceId": "b1g73121-55c4-9238-l39j-ek60dc91872g", "provider" : "signicatvideoid", "videoidProviderOptions" : { "docTypes" : [138,169,147,245,277], "defaultId" : 138 } } ``` ```json title="Example: ReuseID step-up request body" { "userId": "a1e26081-35b4-4557-a46a-ef50bc91672f", "deviceId": "b1g73121-55c4-9238-l39j-ek60dc91872g", "provider" : "readid" } ``` 3. Click the **Send** button. ```json title="Example: ReuseID step-up response" { "data": { "status": "Pending", "transactionId": "0160e8b9-dabc-4a16-b995-29d88e6f102f", "userId": "0eb66632-88d0-4ef4-8126-495c64a0abd2", "deviceId": "f8d74181-9e00-41ba-ba4f-43aa6a3dfea5", "dossierId": "e73801d2-3e7f-4184-8fda-67cc3b03416d", "processId": "0dca14cf-957d-46d9-b374-520f9c650859" } } ``` 4. Open the Authenticator App. 5. The app shows a dialogue box asking you to authenticate before you can verify your identity. 6. Click the **Continue** button. 7. Authenticate in the app with biometrics (or PIN if biometrics is not enabled). 8. Follow the instructions for the identity proofing process. 9. Once you completed the flow in the Authenticator app go back to Postman. 10. In Postman, Navigate to **Step-up** > **Get step-up**. 11. Under the **Params** tab, update the value of `transactionId` to the value you obtained in the **Start step-up** response. 12. Click the **Send** button. ```json title="Example: Get result of ReuseID step-up" { "data": { "transactionId": "e35ebbf7-9631-4966-9762-ae939c80eda1", "userId": "cdf82275-1bbb-4756-9cb6-7e51ac3f480b", "deviceId": "3a1ba38a-0303-4de9-a696-1dc2a6d13614", "proofingId": "30745db7-4403-4403-aa7e-cb35435ee565", "dossierId": "3d563ac4-9d26-4a6a-b58d-5a29cacfe015", "processId": "2f54b0a4-1a77-42e2-98d8-369116ef2055", "status": "Completed", "userData": { "firstName": "JANE", "lastName": "SMITH", "dateOfBirth": "1990-01-01", "gender": "F", "nationality": "NOR" } } } ``` :::note Success! You have now completed a ready-made flow for step-up on ReuseID with eIDV and MobileID authentication. ::: :::details What does it look like in the Authenticator App? ::: ## Review the identity proofing process The identity proofing is handled by our ID Document and Biometric Verification products. The stored result is linked to the ReuseID user that performed the process. You can use our APIs to: - Get all identity verifications for an end-user. - Get the full data set for the process. You can learn how to carry our these operations in our API reference documentation: * [**Get identity verifications for user**](pathname:///apis/reuseid/#tag/User/operation/getIDVerifications): Get all identity verifications for a user with our ReuseID API * [**Get details for process**](pathname:///apis/id-document-and-biometric-verification/#tag/Processes): Get all process details with our ID Document and Biometric Verification API ## Reuse the ReuseID In this guide we leverage MobileID devices for authentication, the key to make the ReuseID user reusable. You can learn about how to get started with our MobileID device operations and the features that it offers in our MobileID developer documentation: * [**MobileID quick start guide**](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication/#3-authenticate-with-mobileid): Learn how to trigger authentications and authorisations * [**ReuseID API reference**](pathname:///apis/reuseid/#tag/MobileID-Authentication): Look up all MobileID API endpoints and properties. View sample requests and responses * [**MobileID features**](/docs/mobile-identity/mobileid/features/): Learn about all MobileID features ## Manage the users You can manage your ReuseID users and their MobileID devices with our ReuseID APIs. You can learn how to carry our these operations in our API reference documentation: * [**Manage your end-users**](pathname:///apis/reuseid/#tag/User): Manage your end-users with our ReuseID User API * [**Manage your end-users' devices**](pathname:///apis/reuseid/#tag/MobileID-device-management): Manage your end-users' devices with our MobileID Device management API --- ## Quick start guides(4) Our quick start guides show you how to test our ReuseID with API requests and a tool of your choice. :::tip Tip ReuseID is flexible, which means that you can choose the underlying components to include for your solution. Use the buttons in the sections below to pick a quick start guide that suits your use case. ::: :::info Want to try without coding? If you want to try out basic ReuseID operations using our no-code interface in the Signicat Dashboard, then see the [Try it out](/docs/reuseid/quick-start-guides/try-it-out) page. ::: ## ReuseID authentication The guides in this section show examples of how you can get started with ReuseID using only the authentication component. Currently, we offer authentication with **MobileID** and **passkeys**. :::note Want to add identity proofing? To combine this with an with an identity proofing onboarding component, see the [ReuseID onboarding and authentication](#reuseid-onboarding-and-authentication) section below. ::: These guides show you how to: - Create a new ReuseID user. - Activate an authentication method. - Authenticate a ReuseID user. * [**MobileID authentication**](/docs/mobile-identity/mobileid/quick-start-guides/mobileid-authentication): Learn how to do a MobileID authentication using our ReuseID API * [**Passkeys authentication**](/docs/passkeys/quick-start-guides/passkeys-authentication): Learn how to do a Passkeys authentication using our ReuseID API ## ReuseID onboarding and authentication The guide in this section shows an example of how you can get started with ReuseID using authentication and identity proofing components with our ready-made flows. This guide shows you how to: - Create a new ReuseID user. - Activate an authentication method. - Perform an identity proofing. - Authenticate a ReuseID user. * [**ReuseID onboarding and authentication ready-made flow**](/docs/reuseid/quick-start-guides/identity-proofing): Learn how to do a ReuseID onboarding and authentication using a ready-made flow with our APIs --- ## Try it out(3) The **Try it out** page in the Signicat Dashboard is the quickest way for you to test out ReuseID. All you need is: - An account in the Signicat Dashboard - A mobile device Use the simple interface to perform ReuseID onboardings and authentications with the click of a button. No coding is required. To test it yourself, see the [Try it out](https://dashboard.signicat.com/reuseid/try-it-out) page and follow the on-screen instructions. ### Tutorial video This video shows you how to use the ReuseID **Try it out** page in the Signicat Dashboard. ### How to start over You can try out the onboarding process as many times as you like. To start over, you need to deactivate the existing account on the device. To do this, open the menu in the Authenticator App, then press the **Deactivate** button. Once deactivated, you can begin a new onboarding. --- ## Release notes(3) To view the release notes, make a selection using the buttons below: ## MobileID authentication * [**MobileID service**](/docs/mobile-identity/mobileid/release-notes/service): View the release notes for the MobileID service * [**Mobile SDKs**](/docs/mobile-identity/mobileid/release-notes/mobile-sdks): View the release notes for our Android and iOS SDKs * [**Authenticator App**](/docs/mobile-identity/mobileid/release-notes/authenticator-app): View the release notes for our Authenticator App ## Identity proofing * [**Ready-made flows**](/docs/reuseid/release-notes/ready-made-flows): View the release notes for our ready-made onboarding and step-up flows --- ## Ready-made flows(Release-notes) :::info Follow the release notes on this page for the latest updates. ::: ## 2025 ### 12.09.2025 #### Updated request body format We have made three changes to the request body format: - The input wrapper object has been removed. - To reflect the underlying products, we have renamed the object `eidProviderOptions` to `videoidProviderOptions`. - Added a provider attribute which can be used to specify the provider to be used in the identity proofing stage of the flow. Currently, the possible values are VideoID and ReadID. :::note Note These changes are backwards compatible. ::: ```json title="Example: New request body" { "provider" : "videoid", "videoidProviderOptions" : { "docTypes" : [138,169,147,245,277,134], "defaultId" : 138 } } ``` ### 12.06.2025 #### Signicat Dashboard ##### Try out ReuseID in the Signicat Dashboard It is now possible to try out ReuseID in the Signicat Dashboard. On the new **Try it out** page, you can: - Install our Authenticator App on iOS or Android by scanning a QR code. - Scan a QR code to configure the app for your account. - Carry out onboarding and authentications. - Manage your users. To test it yourself, see the [Try it out](https://dashboard.signicat.com/reuseid/try-it-out) page! ## 2024 ### 24.10.2024 #### Added eID provider options object to the request body We have updated the format of the request body for both onboarding and step-up. Now, the optional documentation configurations for the VideoID process are moved to their own object called `eidProviderOptions`. ```json title="Example: New request body" { "input": { "eidProviderOptions" : { "docTypes" : [138,169,147,245,277,134], "defaultId" : 138 } } } ``` --- ## Use cases(Reuseid) On this page, you can explore some examples of how and where ReuseID is being used today. ## Examples ReuseID is built flexibly, to enable you to implement any use case that you might have. You can use the buttons below to explore examples of how you can use ReuseID with our supported authentication methods: ### MobileID devices * [**Account recovery**](/docs/mobile-identity/mobileid/use-cases/account-recovery-face-authentication): Use our account recovery feature to avoid a full new onboarding for your end-users * [**App login**](/docs/mobile-identity/mobileid/use-cases/app-login): Use biometrics to log in to your mobile app * [**App transaction**](/docs/mobile-identity/mobileid/use-cases/app-transaction): Use biometrics to perform transactions in your mobile app * [**Identity fraud prevention**](/docs/mobile-identity/mobileid/use-cases/identity-fraud-prevention): Use our face authentication to prevent fraudsters from gaining access to accounts and prevent account takeovers * [**Reset authentication credentials**](/docs/mobile-identity/mobileid/use-cases/reset-authentication-credentials): Use our face authentication to avoid a full new onboarding for your end-users * [**Web login with username**](/docs/mobile-identity/mobileid/use-cases/web-login-username): Use your mobile app to log in to your website without the need for passwords * [**Web login with QR code**](/docs/mobile-identity/mobileid/use-cases/web-login-qr-code): Use your mobile app to log in to your website without the need for usernames or passwords ### Passkeys * [**Shared computer login**](/docs/passkeys/use-cases/shared-computer-login): Use passkeys to authenticate multiple employees on a shared computer * [**Web login**](/docs/passkeys/use-cases/web-login): Use passkeys to authenticate your end-users on your website --- ## Secure Share(Secure-share) Secure Share enables you to securely share files with other people. You can choose among different levels of security, ranging from weaker methods, such as One-Time Passwords (OTPs), to stronger methods, like using electronic IDs (eIDs). :::note Documentation coming soon If you want to get started with Secure Share, contact us for more information and technical documentation: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: {/* ## Get started * [**Quick start guide**](/docs/secure-share/quick-start-guide): Get started with Secure Share ## Concepts * [**How it works**](/docs/secure-share/how-it-works): Learn about the concepts at the core of Secure Share */} ## API * [**Secure Share API**](/apis/secure-share/): Share files securely with other people programmatically with an API If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Custom attributes SIAM stores a number of user and organisation attributes like name, email or address. You can find an overview of all attributes under **Attributes** in the left menu. Here, you can see attributes organised by categories: - **User**: Attributes that apply to a user profile like name and contact. - **Organisation**: Attributes that apply to companies like branch offices and business address. - **Membership**: User attributes in the context of an organisation like business email or phone number. SIAM provides a list of predefined attributes that serve most cases. In addition to these predefined attributes, you can add custom attributes for each category. ## Creating attributes In SIAM, you can add attributes to customise the details you request from users and organisation. To create a custom attribute, do the following: 1. In the **Attributes** section, select **+ Create attribute** at the top right. 2. In the "Create attribute" page, configure the fields according to the [Attribute specifications](#attribute-specifications) table. 3. Click **Create** to create the attribute. After you create a new attribute, you can view it in the **Attributes** section. :::info New attributes and existing profiles When you create an attribute and set it to *required*, the attribute is automatically added to existing user or organisation profiles. ::: ### Attribute specifications | Field name | Description | Required | Allowed values | | -------------- | ---------- | -------- | --------------------------------------------------- | | Type | The type of the attribute. Cannot be changed after creation. | | `User`, `Organisation`, `Membership`.| | Display name | A unique name for the attribute. | | Must start with a letter. Max 128 characters long. | | Property name | The key stored in the JSON object of the attribute in the API. Cannot be changed after creation. | | Text | | Data type | The format of the data. Cannot be changed after creation. | | Can only be one of `Boolean`, `Date`, `Integer`, `String`. Learn more in the [Attribute data types](#attribute-data-types) table below. | | Default value | A suggested value displayed in the field. | | Same as data type. | | Required | Determines whether the attribute must have a value or can be left blank. | | On/Off | | Editable by admin | Determines whether an admin can edit the value of the attribute in the user profile. Applies to custom attributes only. | | On/Off | | Editable by user | Determines whether a user can update the value of the attribute in their profile. Applies to custom attributes only. | | On/Off | :::tip Display name Each attribute name (either custom or predefined) should be unique. ::: ### Attribute data types | Data type | Allowed values | | ------- | -------------------------------------------- | | Boolean | `False`,`True` | | Date | Any date in `YYYY-MM-DD` format. | | Integer | Positive or negative **non-decimal** numbers. | | String | Any character, symbol or digit. | --- ## How it works(Siam) **Signicat IAM (SIAM)** is an identity and authentication product that allows you to create and manage user identities. Your users can use one or two factors to securely authenticate themselves and login to your service. SIAM consists of two main components: - **Platform**: A GUI for managing and storing users, attributes, organisations and login settings. When you activate SIAM, you receive access to your own platform. - **SCIM REST API**: Follows SCIM standard to manage uses, attributes and organisations programmatically. ## Key features SIAM is designed to help you manage users and control their access to your resources. Some of the operations you can do are: - Create and manage user accounts. - Invite and grant access to users. - Enrich user profiles with custom attributes for both users and organisations. - Enhance the security of user accounts with two-factor authentication. - Support delegated and hierarchical user management through roles, permissions and access rights. ## The SIAM platform Once you activate SIAM in the Signicat Dashboard, you receive access to a custom platform with a visual interface designed for your needs. Here you can invite users, assign and create roles, and customise many aspects of digital identity management. The SIAM platform is where you, as an SuperAdmin, can administer and view all your users, including their profile details, access rights and settings. You can also find an overview of the organisations, number of active users, permissions and the monthly login sessions and authentications. ### Key operations Some of the actions you can perform on the SIAM platform are: - Add or update users and organisations. - Assign and revoke admin rights. - Manage roles and permissions. - Invite new users and view existing users' attributes. - Manage and delete custom organisation and user attributes. - View and update your own SIAM account settings. ### Users Users are at the core of SIAM. Users are grouped into organisations, a logical boundary for you to handle multiple scenarios. Users have access to their profile, 2FA settings, trusted devices (when permitted) and login history. You, as an admin, assign roles to your users to determine what actions they are allowed to perform. Admin users have special rights to complete advanced management operations. To log in to SIAM, users require: - Username, or email address, and a password - Optional. Second factor through an authenticator app ### Custom attributes You also have the flexibility to define and add custom attributes to resource profiles. Attributes can apply to a user, an organisation or specify membership to an organisation. For example, address and phone number are default custom attributes that you can add to your users' profiles. SIAM offers a range of attributes for different use cases. Note that identity attributes are stored in SIAM as key-value pairs. ### Theming and hosting SIAM supports theming for branding. To find out how to integrate theming in your SIAM platform, see the [Theming](/docs/dashboard/branding/theming.mdx) documentation. Also, you can host the SIAM platform at your custom domain. To learn more about domains and how to create a custom domain in your Signicat account, see the [Domains](/docs/dashboard/organisation-management/domains/) documentation. ## User management with SCIM REST API SIAM is built around the SCIM REST API that includes endpoints to perform operations programmatically through HTTP requests. The API allows you to: - Create new users - Get a user profile and its attributes - Update a user and its attributes - Deactivate users - Lock and unlock user access To learn more about the Signicat IAM SCIM REST API, see the [API reference](/apis/siam/) documentation. --- ## Signicat IAM Whether it's onboarding new users, assigning user rights or recognising the same user through different electronic ID (eID) methods, user management of your online services involves a lot of work. **Signicat IAM (SIAM)** offers everything you need to manage user accounts, authorisations and identities in one place. SIAM is suitable for scenarios that combine setting user roles, rights and organisations with different login methods. SIAM is an advanced user management solution developed by Signicat that allows you to manage your user accounts seamlessly and securely in one place, the SIAM Dashboard, and programmatically through an API, the Signicat IAM SCIM API. :::tip Want to manage users with SIAM? If you are a new customer interested in using SIAM, contact our digital identity experts: [**Contact us**](https://www.signicat.com/contact/contact-sales) ::: ## Get started * [**Quick start guide**](/docs/siam/quick-start-guide): Get started with SIAM * [**How it works**](/docs/siam/how-it-works): Learn about the concepts at the core of SIAM ## API * [**Signicat IAM SCIM API**](/apis/siam/): Perform identity and access management operations programmatically ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Managing roles The roles of a user can be managed by a **SuperAdmin** from the **Roles** section of the left menu where you can manage roles and permissions. Here, you can: - Find predefined and custom roles. - Create, update and delete custom roles. ## About roles and permissions Roles are groups of permissions that you can assign to the users in your SIAM platform. A role contains one or more _permissions_, which offer a granular way of specifying rights of action. **Predefined roles** SIAM provides default roles that you can use to give granular access to users. These roles are created by Signicat to provide you with common groups of permissions that apply to basic cases. **Custom roles** SIAM also lets you define your own custom roles to follow your principles and policies for identity and access management. **Permissions** Permissions encode actions that users can perform on resources in SIAM, such as the ability to view a page or invite other users. To give permissions to users, you assign them roles. In SIAM, you can assign predefined roles or create new ones depending on the use case. ## Predefined roles When you navigate to the **Roles** section of the left menu, you can view the predefined roles created for you by SIAM. These are described in the table below: :::CustomTable{columnWidths="25% 25% 50%"} | Basic role | Action | Permissions | |:-----------|:-------|:------------| | **Viewer** | Read | Permissions for read-only actions that do not affect state, such as viewing (but not modifying) existing resources or data. | | **Editor** | Create, Read, Update, Delete | All viewer permissions, *plus* permissions for actions that modify state, such as editing existing resources. | | **SuperAdmin** | All + Invite users | All Editor permissions, *plus* elevated permission to invite, remove and grant access to users. | ::: ## Creating roles When you create a new role, you define the scope of actions and operations that users can perform. These are represented as permissions. To create a new role, do the following: 1. In the **Roles** section, select **+ Create new role** at the top right. 2. In the create role page, configure the following: - **Name**: The title of the role. - **ID**: The identifier of the role. - **Description**: Human-readable summary of the role's purpose. - **Category**: The class of the role. - **Permissions**: The set of permissions to include in the scope of this role. Learn more in the [Permissions](#permissions) section below. - **Tags**: Labels for you to organised and identify similar roles. 3. Click **Create** to create the role with this configuration. After you create a new role, you can view it in the **Roles** section and start assigning to your users. ## Assigning roles to users Roles determine the kind of operations users can perform in the SIAM-managed environment. You can control the scope of a role you assign by deciding whether it applies globally or only at the organisation level (scope). You can assign, edit or remove roles from users in **Access** section of the left menu. To grant a role to an existing user, do the following: 1. In the **Access** section, select **+ Grant access** at the top right. 2. In the "Grant access" menu, configure the following: - To assign a role at the global level (across all organisations and hierarchies), tick the **Global access** box. To limit the scope of the role to a specific organisation, leave the box unticked and choose an organisation under **Scope**. - To select a user, select **+ Add** and select a user. - To add roles, select **+ Add** and select the roles to associate with the user. 4. Click **Save** to apply the changes. :::tip Note Users receive an email when you edit their roles. For the new roles to take effect, users must log in again. ::: ## Permissions In SIAM, permissions follow a structured naming convention using the format `:::`. For example, the `signicat:ownidp:roles:create` permission allows a user to create new roles in SIAM. To help you understand and apply this model, the tables below describe the different parts of the permission string and how the associated operations work. ### CRUD legend matrix First, the CRUD operations table explains the actions that can be performed on a resource. The CRUD (Create, Read, Update, Delete) acronym in the below table has the following meaning: :::CustomTable{columnWidths="40% 60%"} | Operation | Meaning | |-----------|-------------------------------| | `create` | Create new resources. | | `read` | View or list resources. | | `update` | Modify existing resources. | | `delete` | Deactivate resources. | | `create:undelete` | Restore a resource after a `delete` deactivated it. | | `delete-permanent` | Permanently delete resources. | ::: ### Permission components table The permission components table outlines how the `` elements defines the scope of a permission. This is matched to most of the CRUD operations in SIAM. :::CustomTable{columnWidths="40% 60%"} | Permission | Definition | |:-----------|:------------| | `signicat:ownidp:permissions:*` | Relates to operations for managing permissions. | | `signicat:ownidp:roles:*` | Relates to operations for managing roles. | | `signicat:ownidp:memberships:*` | Associates users to organisations. | | `signicat:ownidp:user-groups:*` | Relates to operations for managing organisations. | | `signicat:ownidp:subjects:*` | Relates to operations for managing users. | | `signicat:ownidp:subjects:enable` | Allows you to enable or disable user access. | | `signicat:ownidp:subjects:lock` | Allows you to suspend users activities until an event happens, like reset password, or suspend after failed login attempts. | | `signicat:owndip:subjects:update-credentials` | Allows updating the email and username of a user. | | `signicat:ownidp:invitations:*` | Allows inviting new users to join the platform and granting roles to existing users. | | `signicat:ownidp:form-definitions:*` | Relates to managing property forms to define groups of attributes. | | `signicat:ownidp:customer-settings:*` | Relates to rights for configuring platform-level settings. | | `signicat:ownidp:validators:*` | Relates to rules for validating attributes. | | `signicat:ownidp:categories:*` | Allows managing categories to group together roles with similar features. | | `signicat:ownidp:tags:*` | Relates to managing tags. Tags helps you organise and find resources more easily. | | `signicat:ownidp:subject-attribute-definition:*` | Relates to managing custom attributes for users. | | `signicat:ownidp:group-attribute-definition:*` | Relates to managing custom attributes for organisations. | | `signicat:ownidp:membership-attribute-definition:*` | Relates to managing custom attributes for memberships. | | `signicat:ownidp:external-idp:*` | Allows integrating external identity providers into the SIAM platform. | ::: --- ## Managing users(Siam) As a SuperAdmin or Editor user, you can manage the users within your organisation(s). An overview of all users can be found under **Users** in the left menu. Here, you can see an overview of all users that have been invited to your SIAM platform, as well as invite new users. In the **Users** section, you can view more details on each user by selecting the user email or expanding the ellipsis in the same row. The Users section gives an overview of all users, which organisation they belong to, what roles they hold, when they last logged in, when they created their account and if their accounts are active. You can also edit or delete users from here. ## Inviting users To invite a new user to join your SIAM platform, do this: 1. Navigate to the **Users** section. 2. Select the **Invite users** button. 3. Enter the following: - **Email**: The email address of the user being invited. - **First name**: Optional. The first name of the user to show in their profile. - **Last name**: Optional. The last name of the user to show in their profile. - **Organisation**: The organisation to invite the user to. 4. Add which roles to grant to this user within the organisation. 5. Click **Send Invite** to invite the user. When the invitation is sent, you will receive a notification with a success message. The user you invited will receive an email with instructions on how to finalise and activate their account. :::warning Important The invitation email is only valid for **1 hour** by default. Learn more about configuring this setting in the [SIAM settings](/docs/siam/siam-settings.mdx) documentation. ::: Once a user joins, you can review and edit their details in the **Users** section. --- ## Quick start guide(Siam) # Quick start guide Learn how to set up and configure your Signicat IAM (SIAM) platform. This quick start guide shows you how to: 1. Activate SIAM from the Signicat Dashboard. 2. Register and access your SIAM account. 3. Get to know the SIAM platform. ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::note Domains The default domain you create in the Signicat Dashboard will be used as the base URL for your SIAM instance. After SIAM is created, you can access and manage the platform directly at your domain. ::: ## Set it up To create and access your SIAM platform, you first need to activate it from the Signicat Dashboard. Once you have activated SIAM, you need to register an account where you can then start managing users and organisations. ### 1. Activate SIAM :::info What roles do you need? Only users with the `Organisation Admin` or the `Partner Organisation Admin` role in the Signicat Dashboard can activate SIAM. ::: To activate and create your SIAM instance in the Signicat Dashboard, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**SIAM**](https://dashboard.signicat.com/activate-siam/). 2. Click the **Activate SIAM** button. If you require help from our onboarding team, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::note SIAM activation After you activate SIAM, it may take a short while for the product instance to be created in the background. When the instance is ready, you will receive a notification in the Signicat Dashboard and an email. ::: ### 2. Open the invitation email After you have activated SIAM, it is ready to use. You will receive a confirmation email with further instructions to continue with the setup. :::note Who receives the invitation email? Note that all users with role **OrganisationAdmin** in your organisation will receive the invitation email to sign up. ::: To create your SIAM account and complete the setup, do the following: 1. Go to your email. This is the same email address that you used to register your user profile in the Signicat Dashboard. 2. Open the confirmation email from Signicat. 3. Click the verification link to confirm your email address and continue with the setup. The link takes you to your SIAM platform URL, where you can create your account. If you do not see the email, check your spam folder. If you did not receive an email, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### 3. Create your SIAM account After you confirm the invitation, you are redirected to your SIAM URL where to create your user account. To do this: 1. Register in the SIAM platform using your email and password. 2. Configure two-factor authentication. Open your preferred multi-factor authenticator app (such as Google Authenticator or Authy) on your mobile phone and either: - Scan the QR code displayed, or - Enter the secret key manually. 3. Verify the TOTP Code. Enter the 6-digit code generated by your authenticator app to confirm your 2FA setup. 4. Save your recovery codes securely. These codes allow you to access your account if you lose access to your authenticator app. :::info Your role When you register your account in SIAM, your user is automatically assigned the **SuperAdmin** role. Learn more about roles in the [Managing roles](/docs/siam/managing-roles.mdx) documentation. ::: For all future logins, you will need both your password and a code from your TOTP app to access your account. :::note Success! You have now set up your SIAM account. ::: ## Log in to SIAM :::note Where to find the SIAM platform URL The SIAM platform is available at the URL of the default domain you registered in the Signicat Dashboard. ::: You have now completed all required preparations and are ready to log in to your SIAM platform and familiarise yourself with the user interface. To do this, visit your SIAM platform URL and log in with the credentials you used upon registration. :::note Success! You are now ready to explore your SIAM environment. ::: ## Get to know SIAM After you log in to your SIAM platform, you are ready to start managing users and roles in your organisation. Explore the potential of SIAM by continuing with one of our guides below: * [**Managing users**](/docs/siam/managing-users): View and edit details about the users within your organisation(s) * [**Managing roles**](/docs/siam/managing-roles): Create and assign roles to the users within your organisation(s) * [**Custom attributes**](/docs/siam/custom-attributes): Create and manage attributes to enrich user profiles and define membership. * [**SIAM settings**](/docs/siam/siam-settings): Configure login and authentication settings. ## Learn more Dive deep into the documentation to learn more about how Signicat IAM works or how to manage resources programmatically with the SIAM API. * [**How it works**](/docs/siam/how-it-works): Learn about the concepts at the core of SIAM * [**Signicat IAM SCIM API**](/apis/siam/): Perform identity and access management operations programmatically --- ## SIAM settings You can find and manage settings in the **Settings** section on the left menu of your SIAM platform. This page lists the key identity and access management (IAM) settings that you can control in SIAM. These settings control authentication, password policies, account locking, user invitations, and two-factor authentication (TOTP). ## Login settings :::CustomTable | Setting | Description | Default value | Allowed values | |-------------|----------------|---------------|-----------------| | **Login URL** | The URL path where you find the homepage in you SIAM platform. This is appended to the base URL. | `/dashboard` | Any valid URL path | | **Auth Session TTL** | The maximum duration an authenticated session remains valid before the user needs to log in again. | 30 minutes | 1-60 minutes | | **Auto Login Enabled** | This feature is tied to invitation/self-registration. If enabled, users are automatically logged in (without having to enter their credentials) after they register an account. | Off | On / Off | | **Auto Login Cookie TTL** | Available with **Auto Login Enabled**. The duration the login cookie remains valid before the user needs to log in again. | 60 | 3-60 minutes | | **Soft Lock Enabled** | Enables temporary locking (suspended) of an account after repeated failed login attempts. | On | On / Off | | **Soft Lock Allowed Attempts** | The number of consecutive failed login attempts permitted before a user account is suspended (soft lock). | 5 | 3-20 | | **Soft Lock Duration** | The period during which a user account remains suspended (after a soft lock). | 15 minutes | 1-2880 minutes (48 hours) | | **Soft Lock Counter Reset Period** | The time after which the failed login attempt counter resets if no further failures occur. | 30 minutes | 1-30 minutes | | **Hard Lock Enabled** | Permanently locks an account after a defined number of failed login attempts. | Off | On / Off | | **Soft Lock Amount Until Hard Lock** | The number of suspensions (soft lock) before the user account is blocked (hard lock). | 5 | 2-10 | | **Hard Lock Counter Reset Period** | The number of hours an account is blocked for before access is restored. | - | 6-72 hours | | **Password Minimum Length** | The minimum number of characters required in a user password. | 8 | 8-60 characters | | **Password Minimum Digits** | The minimum number of numeric characters required in a password. | 1 | 1-15 | | **Password Minimum Lowercase Letters** | The minimum number of lowercase alphabetical characters required. | 1 | 1-15 | | **Password Minimum Uppercase Letters** | The minimum number of uppercase alphabetical characters required. | 1 | 1-15 | | **Password Minimum Special Characters** | The minimum number of non-alphanumeric characters required. | 1 | 0-15 | ::: ## Time-based One-time Password (TOTP) :::CustomTable | Setting | Description | Default value | Allowed values | |--------------------|---------------------|-----------------|-----------------------| | **TOTP Authentication Issuer** | The name of the issuer displayed in Authenticator apps when setting up two-factor authentication. | Organisation name | Any string | | **TOTP User Enabled** | Enables TOTP-based two-factor authentication for end users. | On | On / Off | | **TOTP Admin Enabled** | Enables TOTP-based two-factor authentication for administrators. | On | On / Off | | **TOTP Cookie TTL in Minutes** | The duration for which the TOTP cookie remains valid when users tick the "Remind me" box. You can set the unit to minutes or hours. | 10020 minutes | 1-1440 minutes (or equivalent in user-selected unit) | ::: ## Registration settings :::CustomTable | Setting | Description | Default value | Allowed values | |--------------|-----------------------|---------------|--------------------------------| | **Invite Registration Enabled** | Allows users to register using an invitation sent by an administrator. | On | On / Off | | **Minutes before invitation/registration expires** | The time after which a user invitation expires. | 60 minutes | 2-14400 minutes | | **Expired Invitations Cleanup Enabled** | Automatically removes invitations that have passed their expiration date. | On | On / Off | | **Maximum Days for Expired Invitations** | The number of days after which an unused invitation is considered expired and removed. | 30 | 2-90 | | **Update Invitations Statuses Enabled** | Periodically updates the status of invitations to keep records accurate. | On | On / Off | ::: --- ## Sign API v2 Swedish BankID phone flow for electronic signatures # Sign API v2 Swedish BankID phone flow for electronic signatures Our Sign API v2 is a REST API using European identity providers for creating electronic signatures on contracts, declarations, forms and other documents. :::note Note This page covers only the information needed to integrate with the Swedish BankID phone flow for electronic signatures. For a full integration guide, see our [Sign API v2 documentation](/docs/electronic-signing/sign-api-v2/). ::: ## Swedish BankID phone flow for electronic signatures Swedish BankID offers a feature that allows an office clerk to initiate a signing process on behalf of an end-user (signer) during a call with a bank or other service provider. The office clerk inputs the user's national identification number (NIN) or personal identification number, triggering a signing process. The end-user then receives a push notification in their app to complete the signing. The phone flow begins similarly to a standard signing, where a collection and session are created with the text to be signed, along with the necessary session and collection details. ### How does Swedish BankID phone flow work? The following diagram illustrates the signing process with Swedish BankID phone flow. Sequence diagram showing a signing process with Swedish BankID phone flow For a full integration guide, see our [Sign API v2 documentation](/docs/electronic-signing/sign-api-v2/). --- ## Signicat Archive The Signicat Archive API ensures long‑term integrity, legal compliance and easy access to signed and other documents requiring secure, tamper‑proof retention. :::tip Note If you are an existing customer of our Sign API v2, see our documentation on [archive functionality within our Sign API v2](/docs/electronic-signing/sign-api-v2/features/archive.mdx). ::: ## Use cases - Object submission - Object archiving - Tagging of archived objects - Searching for archived objects - Retrieval of archived objects - Updating of archived objects - Object reports - Object audit logs via API - Retention management ## Set up an API integration Setting up an API integration is the most flexible way of testing our solutions. You can use your preferred IDE, framework, Postman, etc. using credentials provided by Signicat. :::tip Before you start the integration Before you set up an API integration, we recommended that you familiarise yourself with the [OpenAPI reference documentation](/apis/archive/) to learn about available endpoints and their properties. ::: ### Prerequisites Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). ### Using the API The Signicat Archive API allows you to create and manage archive records. Building a document archiving flow through your chosen system, for example our [Sign API v2 documentation](/docs/electronic-signing/sign-api-v2/), consists of the following steps: 1. Upload a document via our Sign API v2 by making a [POST request to the Documents endpoint](pathname:///apis/electronic-signing/sign-api-v2/#tag/Documents/operation/uploadDocument). 2. Manage the document, including signing, where required. 3. Automatically archive the document to the Signicat Archive after your work with the document is completed. 4. Select the document retention period. 5. Add tags to the document. 6. Search for the document by name, date or tags. 7. Retrieve the document from the archive when need. 8. Extract the document report to view the audit log. 9. Schedule your document for automatic deletion at the end of the retention period. ## API reference In our Signicat Archive API reference, you can find information about the available endpoints and properties, as well as sample requests and responses. * [**Signicat Archive API**](/apis/archive): Our REST API for archiving signed documents ## Other integration details - The Signicat Archive API is a REST-based API solution built on top of Signicat's Digital Trust Platform (DTP) Archive. When a file is uploaded, it is packaged into an object that includes the file itself along with its associated metadata, such as the object ID, tags and audit logs. This object model ensures consistent structure and traceability for every stored item. - The Signicat Archive API routes each object to the Digital Trust Platform Archive for persistent storage. Signicat's Digital Trust Platform Archive is the system of record where all objects are managed, indexed and maintained according to internal platform standards. - The archived objects can be accessed and managed following the standard Signicat client API procedure: 1. Get your client credentials. 2. Set permissions. 3. Obtain an access token. 4. Make an API request. - Signicat's Digital Trust Platform is hosted on Google Cloud Platform (GCP), which serves as the final storage destination. All archived objects are ultimately stored in GCP-managed infrastructure, leveraging its scalability, durability and security capabilities. --- ## About Auðkennisappið The Auðkennisappið can be used for authentication in various online services. It is developed by Auðkenni hf. The Auðkennisappið can be used anywhere in the world. The app is not dependent on SIM card technology on mobile phones (like Skilríki á síma). This is especially useful for customers who have non-Icelandic phone numbers and are unable to install the Auðkenni identity with their SIM cards. The app can also be installed on tablets. ## Level of assurance The [eIDAS Regulation](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eIDAS+Levels+of+Assurance) has established three assurance levels for electronic identification, namely "low", "substantial" and "high", where "high" is the highest level of assurance. Auðkennisappið supports LoA 4, which is equivalent to the "high" level of assurance. Since their level of assurance is not notified by eIDAS, please [contact Auðkenni](mailto:audkenni@audkenni.is) if you need more information about the level of assurance. ## Use case examples Auðkennisappið can be used for: - **Digital onboarding**: To be able to apply for a loan, the bank may require a user to register and become a customer of this bank. Auðkennisappið can be used as a stand alone method or in combination with other services provided by Signicat to verify an identity (see for example [ID Document and Biometric verification](/docs/id-document-and-biometric-verification/)). - **Authentication**: When the user has completed the digital onboarding process, Auðkennisappið can be used to log into their account. The authentication will result in a type of response that depends on the type of [authentication protocol](/docs/eid-hub/quick-start/#connect-with-an-authentication-protocol) used. ### Screen example We assume this user has opened their bank application and are asked to identify themselves using the Auðkennisappið: 1. The user enters their personal code. 2. The Auðkennisappið displays a verification code in the login flow and asks the user to verify this code in the app. 3. The user opens the Auðkennisappið and confirms that the verification code is the same by entering a personal PIN code (PIN1 for authentication or PIN2 for signing). :::tip Tip You can also test the end-user flow in the Signicat Dashboard. For more details, see the [Test](/identity-methods/audkenni-app/test/) page. ::: --- ## Attributes reference You use Auðkennisappið to verify the end-user's identity and obtain relevant personal details about them. This page summarises the user information you can request and receive for the following authentication protocols: - [OIDC](#oidc-scopes-and-claims) - [Authentication REST API](#authentication-rest-api-attributes) :::note Want to use SAML 2.0? For integrations using the SAML 2.0 authentication protocol, see the [SAML requested attributes](/docs/eid-hub/saml-2-0/saml-requested-attributes/) page. ::: ## OIDC scopes and claims You can use the following scopes to request user information from an end-user using Auðkennisappið: :::CustomTable | Scope | OIDC Claim | Example | Description | | :---------- | :-------------- | :---------------- |:------------------------------------------------------------------------------------------------------------------------------| | `idp-id` | `idp_id` | `1702901234` | Personal identifier set by the identity provider. | | `nin` | `nin` | `1702901234` | National identification number / personal code number of the end-user, consisting of 11 digits. | | | `nin_type` | `CIVIL` | Type of national identity number. | | | `nin_issuing_country` | `IS` | Issuing country code of the national identity. | | `profile` | `name` | `ANNA TOMASDOTTIR` | Full name of the end-user. | | | `given_name` | `ANNA` | First name of the end-user. | | | `family_name` | `TOMASDOTTIR` | Surname of the end-user. | | | `birthdate` | `1990-02-17` | Date of birth of the end-user (format YYYY-MM-DD). | ::: ### Response example The response example below only shows the section with the user information claims. Scope: `openid profile idp-id nin` ```json { "idp": "audkenni-app", "name": "ANNA TOMASDOTTIR", "family_name": "TOMASDOTTIR", "given_name": "ANNA", "birthdate":"1990-02-17", "nin": "1702901234", "nin_type": "CIVIL", "nin_issuing_country": "IS", } ``` :::tip IdP scoping You can limit which eIDs the end-user can authenticate with. For more details, see the [IdP scoping](/docs/eid-hub/concepts/idp-scoping/) page. ::: ## Authentication REST API attributes The Signicat Authentication REST API supports the following request and response attributes for Auðkennisappið: :::CustomTable | Attributes | Example | Description | | :---------- | :---------------- |:----------------------------------------------------------| | `idpId` | `1702901234` | Personal identifier set by the identity provider. | | `nin` | `1702901234` | National identification number / personal code number of the end-user, consisting of 11 digits. | | `name` | `ANNA TOMASDOTTIR` | Full name of the end-user. | | `given_name` | `ANNA` | First name of the end-user. | | `family_name` | `TOMASDOTTIR` | Surname of the end-user. | | `dateOfBirth` | `1990-02-17` | Date of birth of the end-user (format YYYY-MM-DD). | ::: ### Response example Here is a section of the response showing the user information attributes: ```json "subject": { "id": "2ULSP7fTILirGvQKmJzSX7z3pY6NIYcK4xYnu3hqIO8=", "idpId": "1702901234", "name": "ANNA TOMASDOTTIR", "firstName": "ANNA", "lastName": "TOMASDOTTIR", "dateOfBirth": "1990-02-17", "nin": { "value": "1702901234", "issuingCountry": "IS", "type": "CIVIL" }, } ``` --- ## App2app Request ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": ["name", "firstName", "lastName", "dateOfBirth", "nin", "age"], "additionalParameters": { "authType": "app2app", "callbackUrl": "https://local.dokobit.com/callback", "message": "This is message.", "confirmationMessage": "This is confirmation message." }, "language": "is" } ``` --- ## Notification Request ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": [ "name", "firstName", "lastName", "dateOfBirth", "nin", "age" ], "prefilledInput": { "nin": "17029012345" }, "additionalParameters": { "authType": "notification", "country": "is" } } ``` --- ## Qr Request ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": [ "name", "firstName", "lastName", "dateOfBirth", "nin", "age" ], "prefilledInput": { "nin": "17029012345" }, "additionalParameters": { "authType": "qr" } } ``` --- ## Auðkennisappið The Auðkennisappið can be used for authentication in various online services. Auðkennisappið is developed by Auðkenni hf. :::note Auðkennisappið facts - Main demographics: Iceland - Use cases: Identity proofing and authentication - Supported protocols: OIDC, Authentication REST API, SAML 2.0 - Supported flows: Redirect, headless - Devices: Mobile, desktop - Key attributes: Name, national identity number. - LoA: LoA4 ::: If you want to read more high-level documentation about Auðkennisappið before you start the integration, see [About Auðkennisappið](/identity-methods/audkenni-app/about-audkenni-app.mdx). ## Get started * [**Test in Dashboard**](/identity-methods/audkenni-app/test): Try it out with your sandbox account before you start integrating * [**Integration guide**](/identity-methods/audkenni-app/setup): Learn how to integrate with Auðkennisappið * [**Attributes reference**](/identity-methods/audkenni-app/attribute-reference): Attributes and response examples per protocol ## Tell me more * [**About Auðkennisappið**](/identity-methods/audkenni-app/about-audkenni-app): High-level description of how Auðkennisappið works in a usage context ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Integration guide for Auðkennisappið :::note Have you tried it out in sandbox? We recommend that you [test our services](/identity-methods/audkenni-app/test.mdx) with your sandbox account before implementing them in production. ::: ## Prerequisites Before you can integrate with Auðkennisappið in production, you must complete the following basic onboarding steps: 1. Before you can create a production account, you need to configure Auðkennisappið access with an onboarding manager. To get help with this, please [contact us](https://www.signicat.com/contact/contact-sales). 2. Once you have received the needed permissions, you can create your production account and add the eID to the Signicat Dashboard. See the eID Hub [Quick start guide](/docs/eid-hub/quick-start/) and then return here to resume this guide. ## Choose integration flow and protocol You can choose between the following integration flows and authentication protocols for Auðkennisappið: :::CustomTable{tableName="Flows and protocols" columnWidths="20% 20% 60%"} | Authentication flow | Supported protocol | Description | | ------------------- | ------------ | --------- | | **Redirect** | OpenID Connect, SAML 2.0, Authentication REST API |In a redirect flow, you initiate an authentication session and then redirect the end-user to a URL hosted by Signicat, where they can authenticate. After the end-user has finished the authentication, they are sent back to your application.

**Best for**: Quick setup, minimal coding, and standard brand compliance. | | **Headless** | Authentication REST API | In a headless flow, the frontend and backend components are decoupled, allowing you to build and host your own custom user interface within your app or website. All communication with Signicat occurs directly in the background via backend API requests, giving you complete control over the entire end-user experience.

**Best for**: Seamlessly tailored user journeys, native mobile app integrations, and white-label branding. | For a conceptual description of these flows, see for example the [Authentication REST API](/docs/eid-hub/authentication-api/) page. ## Redirect flow With the redirect flow, you simply initiate a session using one of the supported protocols, and redirect the end-user to the provided redirect URL/URI. For step-by-step instructions per authentication protocol, see the eID Hub [Quick start guide > Build a connection](/docs/eid-hub/quick-start/#build-a-connection). ## Headless flow If you want complete control over the user experience, you can use the headless flow in the Signicat [Authentication REST API](pathname:///apis/eid-hub/). ### Prerequisites Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). > Ensure that you set the **Authentication REST API** permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide. :::info Learn more about the Signicat Authentication REST API - [Authentication REST API](/docs/eid-hub/authentication-api/) for conceptual documentation. - [API Reference](/apis/eid-hub/) for endpoint descriptions. ::: ### 1. Create a new session To create a new session and start an authentication flow, send a POST request to the [/sessions](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. Here are some request examples for different authentication types: ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": [ "name", "firstName", "lastName", "dateOfBirth", "nin", "age" ], "prefilledInput": { "nin": "17029012345" }, "additionalParameters": { "authType": "qr" } } ``` ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": ["name", "firstName", "lastName", "dateOfBirth", "nin", "age"], "additionalParameters": { "authType": "app2app", "callbackUrl": "https://local.dokobit.com/callback", "message": "This is message.", "confirmationMessage": "This is confirmation message." }, "language": "is" } ``` ```json { "allowedProviders": ["audkenni-app"], "flow": "headless", "requestedAttributes": [ "name", "firstName", "lastName", "dateOfBirth", "nin", "age" ], "prefilledInput": { "nin": "17029012345" }, "additionalParameters": { "authType": "notification", "country": "is" } } ``` You set up the authentication process with the following parameters: - [additionalParameters](#additionalparameters) - [prefilledInput](#prefilledinput) - [requestedAttributes](#requestedattributes) #### Initial parameters To initialise a headless authentication with Audkennisappið, you must specify the following required fields in the initial request: :::CustomTable{tableName="Initialise authentication" columnWidths="20% 15% 20% 45%"} | **Field** | **Required** | **Example value** | **Description** | | :------------------| :------------| :-------------------| :-------------------------------| | `allowedProviders` | Yes | `["audkenni-app"]` | MUST have the value `["audkenni-app"]`. | | `flow` | Yes | `headless` | MUST have the value `headless`. | ::: For more detailed field descriptions, see the [API reference](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession). #### additionalParameters You use `additionalParameters` to control the headless flow: :::CustomTable{tableName="additionalParameters" columnWidths="20% 20% 60%"} | Field | Example value | Description | | :----------------- | :----------- | :------------------ | | `authType` | `qr` | Specifies one of the following eID authentication types:
  • **`qr`**: Displays a QR code for the end-user to scan, typically initiating the authentication process from a secondary device.
  • **`web2app`**: Initiates "remote" authentication, typically from a desktop web browser, redirecting the end-user to authenticate in another app.
  • **`app2app`**: Initiates "local" authentication from your native app, redirecting the end-user to authenticate in another app on the same device.
  • **`notification`**: Sends a push notification to the end-user's device, which they can tap to authenticate in another app.
| | `callbackUrl` | `'https://local.dokobit.com/callback',` | This field is required if `web2app` or `app2app` is used as `authType`. | | `message` | `This is message.` | Displays a short text message (max 60 characters) alongside the PIN entry on a single screen. | | `confirmationMessage` | `This is confirmation message.` | Displays a text message (max 200 characters) with **Confirm** and **Cancel** buttons on the first screen, followed by the PIN entry on a second screen. | | `country` | `lt`, `lv` or `ee` | Required if `authType` is set to `notification` and a `nin` is provided in `prefilledInput`. This ensures the push notification is sent to the correct user based on their country and national identity number. | ::: #### requestedAttributes You can request the following user information in the `requestedAttributes` object: :::CustomTable{tableName="requestedAttributes" columnWidths="25% 25% 50%"} | Attributes | Example | Description | | :---------- | :---------------- |:---------------------------------------------------------| | `age ` | `36` | Age of the end-user | | `dateOfBirth` | `1990-02-17` | Date of birth of the end-user (format YYYY-MM-DD). | | `family_name` | `JANSONS` | Surname of the end-user. | `given_name` | `LAURA` | First name of the end-user. | | `idpId` | `49002171234` | Personal identifier set by the identity provider. | | `nin` | `49002171234` | National identification number / personal code number of the end-user, consisting of 11 digits. | | `name` | `LAURA JANSONS` | Full name of the end-user. | ::: #### prefilledInput :::warning notification requires prefilled nin When using the `notification` authentication type in Audkennisappið, you must prefill the `nin` (national identity number) of the user, otherwise the transaction will fail. ::: Example with prefilled `nin`: ```json "prefilledInput": { "nin": "1702901234" } ``` For conceptual documentation about prefilling, see the [eID and Wallet Hub guide > Prefilling user information](/docs/eid-hub/concepts/prefilling-information/). #### Response example Here is a response example from the "Create a session" request for the headless flow: ```json { "id": "425cbb48--...", "accountId": "a-sdge-...", "status": "CREATED", "idpData": { "deviceLink": "https://test.audkenniapp.is/device-link?deviceLinkType=Web2App&sessionToken=..." }, "allowedProviders": [ "audkenni-app" ], "flow": "headless", "requestedAttributes": [ "dateOfBirth", "firstName", "lastName", "name", "nin", "age" ], "sessionLifetime": 1200, "expiresAt": "2026-06-29T11:08:34.9495067+00:00" } ``` The `CREATED` status means the end-user has not started to authenticate yet. The response returns the necessary data directly in the `idpData` object, which you use to drive the authentication in your own custom user interface: :::CustomTable{tableName="idpData" columnWidths="25% 25% 50%"} | Attributes | Example | Description | | :---------- | :---------------- |:------------------------------------------------| | `deviceLink` | `https://eid-name.example.com/device-link?deviceLinkType=QR&elapsedSeconds=1&sessionToken=...` | You need this link when using the following authentication types (`authType`):
  • `qr`: Generate a QR code with this device link.
  • `web2app`: Show a button with this device link.
  • `app2app`: Show a button with this device link.
| | `controlCode` | `2948` | When using the `notification` authentication type, you must show a 4-digit authentication code to the end-user. | ::: ### 2. Obtain user information (Get session status) Make an HTTP GET request to the [/sessions](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) endpoint to poll for information regarding the session and ongoing authentication. Upon successful authentication, a response is returned that contains the user information requested in the "Create a new session" call carried out earlier. #### Request No data specific for Audkennisappið needs to be provided in this request. To get the status of a session, send a GET request to `https://api.signicat.com/auth/rest/sessions/{id}`. You can find the `id` value in the response that was returned when you created the session. #### Response The "Get session status" response contains a status field, which indicates the current status of the session. Below you can see an example response for a successfully completed session for a headless authentication: ```json { "id": "9735a799-...", "accountId": "a-sdge-...", "status": "SUCCESS", "provider": "audkenni-app", "subject": { "id": "xAqEBBlTUbXYWHjLp3-...", "name": "ANNA TOMASDOTTIR", "firstName": "ANNA", "lastName": "TOMASDOTTIR", "dateOfBirth": "1990-02-17", "nin": { "value": "17029012345", "issuingCountry": "IS", "type": "CIVIL" }, "age": "36" }, "loa": "high", "allowedProviders": [ "audkenni-app" ], "language": "is", "flow": "headless", "requestedAttributes": [ "age", "dateOfBirth", "firstName", "lastName", "name", "nin" ], "sessionLifetime": 1200, "expiresAt": "2026-07-03T07:19:28.6439001+00:00" } ``` ## Next steps Dive deeper into Authentication REST API and improve your application with advanced security features: * [**Signicat Authentication REST API**](/docs/eid-hub/authentication-api/): Find out more about available flows in the eID and Wallet Hub documentation * [**Message level encryption (MLE)**](/docs/eid-hub/authentication-api/receive-encrypted-responses): Read more about how to set up encryption * [**API reference**](/apis/eid-hub/): Look up endpoint and parameter details in the reference guide --- ## Test in Dashboard This page describes how to test Auðkennisappið in the Dashboard with your sandbox account before you start integrating in production. In this way you can learn more about available options and how to connect to the eID. ## Setup for testing ### Sign up and add a domain If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ### Add Auðkennisappið Once you have signed up and added a domain, you can add Auðkennisappið to the list of supported eIDs. 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. Add Auðkennisappið ### Download the Auðkenni app You can test authentication flows with the Auðkenni App. You can download the Auðkenni App here: - [Android](https://play.google.com/store/apps/details?id=is.audkenni.app) - [iOS](https://apps.apple.com/is/app/au%C3%B0kenni/id1530922294) ## Test Auðkennisappið In your sandbox account, you can test Auðkennisappið with a few simple steps: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right to start a test session. 3. Optional. If you activated other eIDs, choose Auðkennisappið from the list of providers. 4. Enter your personal code. 5. The Auðkennisappið displays a verification code in the login flow and asks you to verify this code in the app. 6. You open the Auðkennisappið and confirm that the verification code is the same by entering a personal PIN code (PIN1 for authentication and PIN2 for signing). Below, you can see what the flow looks like: --- ## About Skilríki á síma The Skilríki á síma can be used for authentication with various online services. The eID is developed by Auðkenni hf., which is owned by the Icelandic government. The Skilríki á síma relies on SIM cards designed for electronic identification technology and issued by the following mobile service providers in Iceland: Nova, Síminn, Vodafone, Hringdu and Hringidan. SIM cards hold e-certificates, which serve as authentication keys to uniquely identify users. Users can activate Skilríki á síma at their bank or at the branch offices of the mobile service providers. When registering new users, banks and mobile service providers check the identity of their customers before activating the eID. To use Skilríki á síma, users need to have a mobile phone and a special SIM card issued by mobile service providers in Iceland. When authenticating using Skilríki á síma, users receive an SMS with a prompt to validate the authentication request using a personal PIN code. ## Level of assurance The [eIDAS Regulation](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eIDAS+Levels+of+Assurance) establishes three assurance levels for electronic identification: - Low - Substantial - High High is the highest level of assurance (LoA). Skilríki á síma supports LoA4, which is equivalent to the High LoA. Note that the LoA offered by Skilríki á síma is not notified by eIDAS. For more information about the level of assurance of Auðkenni, please [contact Auðkenni](mailto:audkenni@audkenni.is). ## Use case examples Skilríki á síma can be used for: - **Digital onboarding**: To be able to apply for a loan, the bank may require a user to register and become a customer of this bank. Skilríki á síma can be used as a stand alone method or in combination with other services provided by Signicat to verify an identity (see for example [ID Document and Biometric verification](/docs/id-document-and-biometric-verification/)). - **Authentication**: When the user has completed the digital onboarding process, Skilríki á síma can be used to log into their account. The authentication will result in a type of response that depends on the type of [authentication protocol](/docs/eid-hub/) used. ### Screen example When users want to identify themselves using the Skilríki á síma, the following steps occur: 1. On your app or website, the user selects a button to start authenticating. 2. In the login window, the user enters their mobile phone number and selects **Log in** (Innskrá in Icelandic). 3. On the mobile phone, the user receives a login SMS message with a verification code and checks that the code is the same as in the Skilríki á síma login window. If true, the user confirms by selecting **OK** or **Accept**. 4. On the mobile phone, the user enters their personal PIN code (PIN1 for authentication or PIN2 for signing) and selects **OK** or **Send**. 5. Finally, the user has access to your online service. :::tip Tip You can also test the end-user flow in the Signicat Dashboard. For more details, see the [Test](/identity-methods/audkenni-mobileid/test/) page. ::: ## Additional resources Here is a list of useful links to learn more about Skilríki á síma: - [Official Digital Island - Electronic ID by phone](https://island.is/en/electronic-id/electronic-id-by-phone). - [Auðkenni website](https://www.audkenni.is/) --- ## Attributes reference(Audkenni-mobileid) You use Skilríki á síma to verify the identity of end-users and obtain relevant personal details about them. This page summarises the user information you can request and receive for the following authentication protocols: - [OIDC](#oidc-scopes-and-claims) - [Authentication REST API](#authentication-rest-api-attributes) :::note Want to use SAML 2.0? For integrations using the SAML 2.0 authentication protocol, see the [SAML requested attributes](/docs/eid-hub/saml-2-0/saml-requested-attributes/) page. ::: ## OIDC scopes and claims You can use the following scopes to request user information from an end-user using Skilríki á síma: :::CustomTable | Scope | OIDC Claim | Example | Description | | :-------- | :-------------------- | :---------------- |:------------------------------ | | `idp-id` | `idp_id` | `1702901234` | Personal identifier set by the identity provider. | | `nin` | `nin` | `1702901234` | National identification number of the end-user, consisting of 10 digits: the first six are the individual's date of birth in the format `DDMMYY`. | | `nin` | `nin_type` | `CIVIL` | Type of national identity number. | | `nin` | `nin_issuing_country` | `is` | Issuing country code of the national identity. | | `profile` | `name` | `Anna Tomasdottir` | Full name of the end-user. | | `profile` | `given_name` | `Anna` | First name of the end-user. | | `profile` | `family_name` | `Tomasdottir` | Surname of the end-user. | | `profile` | `birthdate` | `1990-02-17` | Date of birth of the end-user (format `YYYY-MM-DD`). | ::: ### Response example The response example below only shows the payload of an OIDC response with all claims on display. Scope: `openid profile idp-id nin` ```json { "iss": "https:///auth/open", "nbf": 1731075893, "iat": 1731075893, "exp": 1731076493, "aud": "", "amr": [ "external" ], "at_hash": "DUfaiUCP6vaBu_Q45EwsUQ", "sid": "59E087F7E27089EDE5516C21B9416113", "sub": "1blgPh97HPXdEY5QsK45sdqtiGacjq5fAd5gC3dlP74=", "auth_time": 1731075879, "idp": "audkenni-mobileid", "idp_id": "1702901234", "name": "Anna Tomasdottir", "family_name": "Tomasdottir", "given_name": "Anna", "birthdate": "1990-02-17", "nin": "1702901234", "nin_type": "CIVIL", "nin_issuing_country": "is", "idp_issuer": "Fullgilt audkenni 2021", "transaction_id": "a46a0f68-bb0e-4244-9428-224518c1b314", } ``` :::tip IdP scoping You can limit which eIDs the end-user can authenticate with. For more details, see the [IdP scoping](/docs/eid-hub/concepts/idp-scoping/) page. ::: ## Authentication REST API attributes The Signicat Authentication REST API supports the following request and response attributes for Skilríki á síma: :::CustomTable{columnWidths="25% 25% 50%"} | Attributes | Example | Description | | :---------- | :---------------- |:-------------------------------| | `idpId` | `1702901234` | Personal identifier set by the identity provider. | | `nin` | `1702901234` | National identification number of the end-user, consisting of 10 digits: the first six are the individual's date of birth in the format `DDMMYY`. | | `name` | `Anna Tomasdottir` | Full name of the end-user. | | `firstName` | `Anna` | First name of the end-user. | | `lastName` | `Tomasdottir` | Surname of the end-user. | | `dateOfBirth` | `1990-02-17` | Date of birth of the end-user (format `YYYY-MM-DD`).| ::: ### Response example Here is a section of the response showing the user information attributes: ```json "subject": { "id": "2ULSP7fTILirGvQKmJzSX7z3pY6NIYcK4xYnu3hqIO8=", "idpId": "1702901234", "name": "Anna Tomasdottir", "firstName": "Anna", "lastName": "Tomasdottir", "dateOfBirth": "1990-02-17", "nin": { "value": "1702901234", "issuingCountry": "IS", "type": "CIVIL" }, } ``` ## SAML 2.0 attributes Integrating with SAML 2.0 supports the following request and response attributes for Skilríki á síma: :::CustomTable{columnWidths="25% 25% 50%"} | Attributes | Example | Description | | :---------- | :---------------- |:-------------------------------| | `idpId` | `1702901234` | Personal identifier set by the identity provider. | | `nin` | `1702901234` | National identification number of the end-user, consisting of 10 digits: the first six are the individual's date of birth in the format `DDMMYY`. | | `name` | `Anna Tomasdottir` | Full name of the end-user. | | `firstName` | `Anna` | First name of the end-user. | | `lastName` | `Tomasdottir` | Surname of the end-user. | | `dateOfBirth` | `1990-02-17` | Date of birth of the end-user (format `YYYY-MM-DD`).| ::: ### Response example Here is a section of the SAML response showing the user information attributes: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... XML_SIGNATURE X509_CERTIFICATE VsQFCIOdsM-brFXDGQhMyMfnlkQyeb8pNfkxq6VFppY= ENTITY_ID 1702901234 1702901234 IS CIVIL Anna Tomasdottir Anna Tomasdottir 1990-02-17 substantial audkenni-mobileid ``` --- ## Skilríki á síma The Skilríki á síma can be used for authentication in various online services. Skilríki á síma is developed by Auðkenni hf. :::note Skilríki á síma facts - Main demographics: Iceland - Use cases: Identity proofing and authentication - Supported protocols: OIDC, Authentication REST API, SAML 2.0 - Devices: Mobile, desktop - Key attributes: Name, national identity number. - LoA: LoA4 ::: If you want to read more high-level documentation about Skilríki á síma before you start the integration, see [About Skilríki á síma](/identity-methods/audkenni-mobileid/about-audkenni-mobileid.mdx). ## Get started * [**Test in Dashboard**](/identity-methods/audkenni-mobileid/test): Try it out with your sandbox account before you start integrating * [**Get started with the integration**](/identity-methods/audkenni-mobileid/setup): Select protocol and configure in production * [**Attributes reference**](/identity-methods/audkenni-mobileid/attribute-reference): Attributes and response examples per protocol ## Tell me more * [**About Skilríki á síma**](/identity-methods/audkenni-mobileid/about-audkenni-mobileid): High-level description of how Skilríki á síma works in a usage context ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Get started with the integration of Skilríki á síma :::note Have you tried it out in sandbox? We recommend that you [test our services](/identity-methods/audkenni-mobileid/test.mdx) with your sandbox account before implementing them in production. ::: ## Prerequisites ### Access to Skilríki á síma Before you can create a production account, you need to configure Skilríki á síma access with an onboarding manager. To get help with this, please [contact us](https://www.signicat.com/contact/contact-sales). ## Create a production account in the Dashboard Once you have received the needed permissions, you can create the account from the Signicat Dashboard: 1. Go to **Signicat Dashboard** > [Organisation management](https://dashboard.signicat.com/org-mgmt/). 2. Click **Add Account**. 3. Enter the name of your account under **Account Name**. 4. Tick the **Production account** type. 5. Click **Create** to create the new account. ## Add eID to the Dashboard 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ## Set up a connection with a protocol To establish a connection between Signicat Skilríki á síma and your application, you need to use a standard authentication protocol. :::tip Supported authentication protocols Signicat supports the standard **OpenID Connect (OIDC)** and **SAML 2.0** protocols. In addition, we offer our bespoke **Signicat Authentication REST API**. The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API. To learn more about these authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: For information about how to set up the different protocols, see the [Quick start guide](/docs/eid-hub/quick-start/). --- ## Test in Dashboard(Audkenni-mobileid) This page describes how to test Skilríki á síma in the Signicat Dashboard using a sandbox account before you start integrating in production. In this way you can learn more about available options and how to connect to the eID. ## Setup for testing ### Sign up and add a domain If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ### Add Skilríki á síma Once you have signed up and added a domain, you can add Skilríki á síma to the list of supported eIDs. 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. Add Skilríki á síma ### Request a SIM card To be able to test the whole login flow, you need access to a SIM card with an e-certificate. Please, contact [Auðkenni](mailto:audkenni@audkenni.is) to get started with this. :::info Test certificates in SIM cards Since it's not possible to have both test certificates and prod certificates on the same SIM card, you need to use separate SIM cards for testing purposes. Note that Auðkenni does not provide public test data, so you need access to a valid SIM card to test your integration. ::: For more information about the Auðkenni test environments, see the [Auðkenni](https://audkenni.atlassian.net/wiki/spaces/DOC/pages/5578194958/Au+kennis+Environments) documentation. ## Test Skilríki á síma In your sandbox account, you can test the Skilríki á síma with a few simple steps: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right to start a test session. 3. Optional, if other eIDs are active in your account: Select Skilríki á síma from the list of identity providers. 4. Enter your mobile phone number. 5. The Skilríki á síma displays a verification code in the login flow and asks you to verify this code on your mobile phone. Select **OK** or **Accept** on your mobile phone. 6. Enter your personal PIN code (PIN1 for authentication and PIN2 for signing) and select **OK** or **Send**. After testing a successful authentication, you can review the user data on the screen. Below, you can see what the flow looks like: --- ## About .beID .beID is the Belgian electronic identity card, which Belgium citizens or EU citizens residing in Belgium can use for secure electronic authentication and signing. The ID-card is a smart card that includes a microchip, which stores personal information. It is issued by the [Belgian government](https://www.ibz.rrn.fgov.be/fr/documents-didentite/eid/) and is available for citizens over 12 years old. For children below 12, a version without the signing function is available (known as Kids-ID). There is also a version for foreign residents. Here is a sample ID-card (specimen): Sample ID-card To be able to use the .beID-card, the user needs: - A USB smart card reader connected to the computer to read the details on the ID-card. - [ID-card client software](https://eid.belgium.be/en) installed on their computer. - PIN code to confirm their identity. The PIN code is issued together with the physical ID card. There are two PIN codes associated with the card, one for authentication and one for signing. The ID-card also includes the needed certificates for authentication and signing. See also the [Test](/identity-methods/beid/test.mdx) page. ## Key features * It produces trusted identities verified by the Belgian government. * Signatures that use .beID are classified as Qualified Electronic Signatures (QES). ## Level of assurance .beID is [eIDAS](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eIDAS+Levels+of+Assurance) certified and supports "high" level of assurance. If you need more information about the level of assurance, please contact the [identity provider](https://eid.belgium.be/en/contact). ## Use case examples .beID can be used for: - **Digital onboarding**: To be able to apply for a loan, the bank may require a user to register and become a customer of this bank. The ID-card can be used as a stand alone method or in combination with other services provided by Signicat to verify an identity (see for example [ID Document and Biometric verification](/docs/id-document-and-biometric-verification/)). - **Authentication**: When the user has completed the digital onboarding process, the ID-card can be used to log into their account. The authentication will result in a type of response that depends on the type of [authentication protocol](/docs/eid-hub/) used. - **Electronic signing**: Your bank customer can apply for a loan and sign the loan application with the ID-card. The same service is used for these use cases. However, the eID can be configured with different flows. For example, onboarding a new customer is a one-time occurrence, while authentication is a repetitive action for the customer. You may set up a simpler user flow for recurring authentications. The [level of assurance](#level-of-assurance) that is required depends on the services you offer. For technical integration details: - For **identity proofing** and **authentication**, see the [eID and Wallet Hub Quick start guide](/docs/eid-hub/quick-start/). - For **signing**, see the [Electronic Signing](/docs/electronic-signing/) documentation. ### Authentication Holders of a .beID card can use it to log into the website of a service provider that supports this method. The following example illustrates a typical authentication session for an end-user holding an ID-card. This example assumes the end-user has already installed the necessary software, connected a card reader and inserted their valid card into the reader. 1. The user selects .beID as login method and is asked to insert the ID-card into their card reader. 2. The user confirms the agreement to the card being read. 3. The user provides their personal PIN code. 4. The user is authenticated from the certificate on the ID-card. The actual screens may have a different graphical profile in your setup. For details about how you can test this flow, see the [Test page](/identity-methods/beid/test.mdx). For details about user information you can retrieve via the .beID, see the [Attributes reference](/identity-methods/beid/attribute-reference.mdx). ### Electronic signatures The .beID card also allows end-users to sign documents electronically through [third-party signing](/docs/electronic-signing/). The signature that is produced in this process is a Qualified Electronic Signature (QES), which has the same legal validity as a traditional handwritten signature on paper. The screenshots below show the end-user flow for signing a document. For technical integration details, see the separate [Electronic Signing](/docs/electronic-signing/) documentation. ## Other sources - [.beID website](https://eid.belgium.be/en) - [.beID information on the Belgian government website](https://www.ibz.rrn.fgov.be/fr/documents-didentite/eid/) {/*### Related eIDs The .beID card solution is not limited to Belgium; Signicat also offers a similar setup of the ID-card solution for Estonia, Lithuania, Latvia, Finland, Iceland, and Poland. */} --- ## Attributes reference(Beid) You use .beID to verify the end-user's identity and obtain relevant personal details about them. This page summarises the user information you can request and receive for the following authentication protocols: - [OIDC](#oidc-scopes-and-claims) - [Authentication REST API](#authentication-rest-api-attributes) :::note Want to use SAML 2.0? For integrations using the SAML 2.0 authentication protocol, see the [SAML requested attributes](/docs/eid-hub/saml-2-0/saml-requested-attributes/) page. ::: :::note Note Data availability varies depending on the type of account you are using. - In a sandbox account, you can test your integration with all available attributes. - In a production account, certain attributes may be restricted by GDPR regulations or subject to specific legislation. In such cases, you must apply for additional authorisation. For additional information, [contact us](mailto:onboarding@signicat.com). ::: :::warning National identity number Use of the Belgian RRN (national identity number) is subject to specific legislation. For certain uses, you must obtain specific authorisation by FOD/SPF IBZ. For more details, refer to the applicable laws (for example, [this one](http://www.ejustice.just.fgov.be/mopdf/2018/12/13_1.pdf#Page11) or other updated, applicable laws). ::: ## OIDC scopes and claims You can use the following scopes to request user information from an end-user using .beID: :::CustomTable | **Scope** | **OIDC Claim** | Example | Description | | :------------ | :----------------------------------- | :------ | :---------- | | `profile` | `name` | `Nora Martens` | Full name of the end-user. | | | `given_name` | `Nora` | First name of the end-user. | | | `family_name` | `Martens` | Surname of the end-user. | | | `middle_name` | | Middle name of the end-user. | | | `gender` | `FEMALE` | Gender of the end-user. | | | `birthdate` | `1990-02-17` | Date of birth of the end-user (format YYYY-MM-DD). | | `nin` | `nin` | `90021700029` | National identification number / personal code number of the end-user, consisting of 11 digits. | | | `nin_type` | `PERSON` | Type of national identity number. | | | `nin_issuing_country` | `BE` | Issuing country code of the national identity. | | `address` | `address` | `Specimenstraat 12,1000,Brussel` | Address of the end-user. | | `nationality` | `nationality` | `BELG` | Nationality of the end-user. | | `beid-extra` | `beid_card_delivery_municipality` | `Brussel` | Municipality that issued the ID-card. | | | `beid_birth_location` | `Leuven` | Birth location of the end-user. | | | `beid_validity_date_begin` | `2017-05-30` | Start date of the ID-card's validity. | | | `beid_document_type` | `belgian_citizen` | Type of identity document; Belgian citizen (over 12 yo), Kids-ID (under 12 yo) or the electronic foreigners card. | | | `beid_validity_date_end` | `2027-05-30` | Last date the ID-card is valid. | | | `beid_card_number` | `000001110749` | Card number on the ID-card. | ::: ### Response example The response example below shows the section with the user information claims. Scope: `openid profile nin address nationality` ```json { "idp_id":"98082100029", "name":"Nora Martens", "family_name":"Martens", "given_name":"Nora Martens", "gender":"FEMALE", "birthdate":"1990-02-17", "address":{"formatted":"Specimenstraat 12,1000,Brussel"}, "nationality":"BELG", "nin":"90021700029", "nin_type":"PERSON", "nin_issuing_country":"BE", "beid_card_delivery_municipality":"Brussel", "beid_birth_location":"Leuven", "beid_validity_date_begin":"2017-05-30", "beid_validity_date_end":"2027-05-30", "beid_document_type":"belgian_citizen", "beid_card_number":"000001110749", "sub":"fIZvCR6CX9wh3Ut-PpDU-q9e9E67pb-vkEpzLiSDVkw=", "idp_issuer":"be-smartcard" } ``` :::tip IdP scoping You can limit which eIDs the end-user can authenticate with. For more details, see the [IdP scoping](/docs/eid-hub/concepts/idp-scoping/) page. ::: ## Authentication REST API attributes The Signicat Authentication REST API supports the following request and response attributes for .beID: :::CustomTable | Attribute | Sub-field | Example | Description | | :----------------------------- | --------- | :------------------------- | ----------- | | `name` | | `Nora Martens` | Full name of the end-user. | | `firstName` | | `Nora` | First name of the end-user. | | `lastName` | | `Martens` | Surname of the end-user. | | `middleName` | | | Middle name of the end-user | | `gender` | | `FEMALE` | Gender of the end-user. | | `dateOfBirth` | | `1990-02-17` | Date of birth of the end-user (format YYYY-MM-DD). | | `nin` | `value` | `90021700029` | National identification number / personal code number of the end-user, consisting of 11 digits. | | | `issuingCountry` | `BE` | Issuing country of the national identity. | | | `type` | `PERSON` | Type of national identity number. | | `address` | | `Specimenstraat 12,1000,Brussel` | Address of the end-user. | | `nationality` | | `BELG` | Nationality of the end-user. | | `beidCardDeliveryMunicipality` | | `Brussel` | Municipality that issued the ID-card. | | `beidBirthLocation` | | `Leuven` | Birth location of the end-user. | | `beidValidityDateBegin` | | `2017-05-30` | Start date of the ID-card's validity. | | `beidDocumentType` | | `belgian_citizen` | Type of identity document; Belgian citizen (over 12 yo), Kids-ID (under 12 yo) or the electronic foreigners card. | | `beidValidityDateEnd` | | `2027-05-30` | Last date the ID-card is valid. | | `beidCardNumber` | | `000001110749` | Card number on the ID card. | ::: ### Response example Here is a response example from the Authentication REST API: ```json { "id": "d728f7f2-9791-2743-815f-04bee72e30ad", "accountId": "a-sdge-...", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=f044eef9-9571-4941-b06f-d98a0615cf6c&transactionId=d728f7f2-9791-2743-815f-04bee72e30ad", "status": "SUCCESS", "provider": "be-smartcard", "subject": { "id": "9P3Hfs-WdctMxpl-slH27DYO0gArxT-JpWGm9AleWfQ=", "idpId": "90021700029", "name": "Nora Martens", "firstName": "Nora Martens", "middleName": "", "lastName": "Specimen", "dateOfBirth": "1990-02-17", "nin": { "value": "90021700029", "issuingCountry": "BE", "type": "PERSON" }, "beidCardDeliveryMunicipality": "Brussel", "beidBirthLocation": "Leuven", "address": "Specimenstraat 12,1000,Brussel", "beidValidityDateBegin": "2017-05-30", "beidDocumentType": "belgian_citizen", "nationality": "BELG", "beidCardNumber": "000001110749", "beidValidityDateEnd": "2027-05-30" }, "callbackUrls": { "success": "https://example.com/success?sessionId=58126fb8-c5e2...", "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...", "error": "https://example.com/error?sessionId=58126fb8-c5e2..." }, "environment": { "ipAddress": "123.45.67.899", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" }, "allowedProviders": [ "beid" ], "flow": "redirect", "requestedAttributes": [ "address", "beidBirthLocation", "beidCardDeliveryMunicipality", "beidCardNumber", "beidDocumentType", "beidValidityDateBegin", "beidValidityDateEnd", "dateOfBirth", "firstName", "gender", "lastName", "middleName", "name", "nationality", "nin", "idpId" ], "sessionLifetime": 1200 } ```` --- ## .beID .beID is the Belgian electronic identity card, which can be used for authentication and signing. :::note .beID facts - Main demographics: Belgium - Use cases: Identity proofing, authentication, electronic signing - Supported protocols: OIDC, Authentication REST API, SAML 2.0 - Devices: Card reader, desktop - Key attributes: Name, national identity number - LoA: High ::: If you want to read more high-level documentation about .beID before you start the integration, see [About .beID](/identity-methods/beid/about-beid.mdx). ## Get started * [**Test in Dashboard**](/identity-methods/beid/test): Try it out with your sandbox account before you start integrating * [**Get started with the integration**](/identity-methods/beid/integrate): Select protocol and configure in production * [**Attributes reference**](/identity-methods/beid/attribute-reference): Attributes and response examples per protocol ## Tell me more * [**About .beID**](/identity-methods/beid/about-beid): High-level description of how .beID works in a usage context ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Get started with the integration :::note Have you tried it out in sandbox? We recommend that you [test our services](/identity-methods/beid/test.mdx) with your sandbox account before implementing them in production. ::: ## Access to .beID Before you can create a production account in the Dashboard, you need to configure .beID access with an onboarding manager. To get help with this, please [contact us](https://www.signicat.com/contact/contact-sales). ## Create a production account Once you have received the needed permissions, you can create the production account from the Signicat Dashboard: 1. Go to **Signicat Dashboard** > [Organisation management](https://dashboard.signicat.com/org-mgmt/). 2. Click **Add Account**. 3. Enter the name of your account under **Account Name**. 4. Tick the **Production account** type. 5. Click **Create** to create the new account. ## Set up domain When you have created a production account, you can add a domain to this account: 1. In the Signicat Dashboard, navigate to **Settings** > [**Domains**](https://dashboard.signicat.com/domains). If you are a member of multiple accounts, make sure you are in the correct account by checking the account name in the top left of the screen. 2. Select **Add domain**. 3. To add a standard (Signicat) domain, enter the name of your subdomain in the **Domain name** field. 4. Select **Add domain** to create the new domain. ## Add .beID 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ## Select protocol To establish a connection between Signicat .beID and your application, you need to use a standard authentication protocol. :::tip Supported authentication protocols Signicat supports the standard **OpenID Connect (OIDC)** and **SAML 2.0** protocols. In addition, we offer our bespoke **Signicat Authentication REST API**. The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API. To learn more about these authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: ## Set up the protocol For information about how to set up the different protocols, see the [Quick start guide](/docs/eid-hub/quick-start/). --- ## Test in Dashboard(Beid) This page describes how to test .beID in the Dashboard with your sandbox account before you start integrating in production. In this way you can learn more about available options and how to connect to the eID. ## Setup for testing To be able to test how the login flow looks for an end-user, you need: - [A test card](#order-test-card) - [A card reader](#purchase-a-card-reader) - [ID-card client software](#install-the-client-software) installed on your computer - [Sign up and add a domain](#sign-up-and-add-domain) - [Add .beID](#add-beid) ### Order test card You can order valid test cards from [eaZyiD](https://www.eazysign.be/en/eazyset-your-set-of-eid-testing-cards). Test credentials and PIN numbers are included in the test card package. ### Purchase a card reader The card reader allows you to insert your ID-card and communicate securely with the [ID client software](#install-the-client-software) on your computer. Most standard USB card readers can be used to read the .beID card, as long as they are labelled “PC/SC compliant” and the corresponding driver is installed. For supported browsers, see the [.beID site](https://eid.belgium.be/en/faq/which-browsers-can-i-use-log). Please consult with the [card issuer](https://www.ibz.rrn.fgov.be/fr/documents-didentite/eid/) for recommendations and where to purchase a card reader (most electronic stores provide them). ### Install the client software The client software enables the communication between the card reader and the ID-card. You can download and install the necessary ID-card software on your computer from [https://eid.belgium.be/en](https://eid.belgium.be/en). ### Sign up and add domain If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ### Add .beID Once you have signed up and added a domain, you can add .beID to the list of supported eIDs. 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. Test .beID ## Test .beID Once you have added .beID to the list of available eIDs in the Dashboard, you can test how it works for the end-user: 1. In the **eIDs** list, select **Test eIDs**. 2. You are now ready to test the ID-card login in Signicat's sandbox environment. Test credentials and PIN numbers are included in the [test card package](#order-test-card). --- ## Buypass :::note Technical documentation coming soon If you want to integrate with Buypass, contact us for more information and technical documentation: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: ## About Buypass Buypass ID is a Norwegian personal electronic ID which can be used for secure electronic identification, signature and payment. Buypass ID can be stored on a Buypass smart card or on a mobile phone. Buypass personal ID can be used both for private services at Buypass user locations and as a personal ID in a business solution. In the latter solution you can combine both local certificates (issued by the company itself), to serve the internal needs of the local logon and qualified certificates (issued by Buypass) on a single smart card. With Buypass ID you can log on to websites, sign contracts electronically and pay in a simple and user-friendly way with a method that fulfils the market's highest level of security requirements. ## Get started with the integration Integration with Buypass is done similarly to other Signicat's eIDs. This section describes how to get started with setting up Buypass. :::info Want to learn more? For general information about integrating with Signicat, see the **eID and Wallet Hub** [Quick start guide](/docs/eid-hub/quick-start/). ::: ### Initial preparations If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ### Add Buypass Once your [Dashboard account is configured](#initial-preparations), you must add Buypass to the list of supported eIDs. :::tip Note Before you can start integrating, you need to configure Buypass access with an onboarding manager. To get help with this, please [contact us](https://www.signicat.com/contact/contact-sales). ::: To add Buypass: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **+ Add new**. 3. Choose Buypass. 4. Select **Add**. ### Certificates You need merchant certificates in both sandbox and production environments. To get help with ordering and installing the certificates, please [contact us](https://www.signicat.com/contact/contact-sales). ### Smart card (Smartkort) Buypass Smartkort is a personal smart card (plastic card) loaded with a certificate. You need a smart card reader to use this to authenticate or sign documents. See also [test information](#test-information). Smart card login ### Buypass mobile app As an alternative to smart cards, Buypass offers a mobile app that the user can use to authenticate instead of the smart card. Mobile login You can download this app from [https://www.buypass.no/produkter/buypass-id-mobil](https://www.buypass.no/produkter/buypass-id-mobil). ## Test information Buypass Support issues test certificates. You may contact Buypass Support at +47 6113 5920, or send an email to [kundeservice@buypass.no](mailto:kundeservice@buypass.no). The certificates are plastic cards. You will need a card and a card reader. Necessary software is made available during test. For information about how to test the smart card, see [Smart card diagnose](https://secure.buypass.no/wips/service?op=DIAG). ## Other sources Read more about Buypass Electronic ID on [https://www.buypass.com/products/id-and-authentication](https://www.buypass.com/products/id-and-authentication). ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## About Czech Bank iD Czech Bank iD is a digital identity verification solution designed to streamline online authentication processes in the Czech Republic. Registered users can log in to digital services using their bank credentials in a convenient and secure way. By leveraging bank-level authentication, Bank iD minimizes the risk of identity fraud while enhancing user experience across platforms. In the Bank iD scheme, banks act as trusted identity providers (IdP) by verifying the identities of their customers through secure login methods. Bank iD is available in Czech Republic for holders of a bank account at one of the participating banks. ## Key features - Czech Bank iD can be used for end-user onboarding (identification) and login (authentication). - Users of Czech Bank iD can: - Proof their identity online with their existing bank account. - Rely on their mobile banking app to verify their identity. - Use multi-factor authentication from their bank to verify their identity. :::info Electronic signing Signicat offers electronic signatures with Czech Bank iD on request. For more information, reach out to our digital identity experts: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: ## Use cases Czech Bank iD is well-suited for the following use cases: **Onboarding / Identification** An end-user wants to create a new account on you website/app. You can use Czech Bank iD, as an identification method, to receive the personal details of the end-user and create their new profile. **Authentication / Login** An end-user, with an existing account, wants to log in to your website/app. You can use Czech Bank iD, as an authentication method, to provide a secure and trusted authentication mechanism to the end-user. **Electronic signing** An end-user wants to sign a legal document with a strong signature. You can facilitate electronic signature flows by leveraging Czech Bank iD as an e-signing method. ## Banks as identity providers The following banks offer log in with Bank iD to their customers: - Air bank - Banka Creditas - Česká spořitelna - KB (Komerční banka) - ČSOB (Ceskoslovenská obchodní banka) - mBank - Moneta Money Bank - Raiffeisen Bank - Partners Banka - UniCredit Bank - Fio banka :::info About the banks In Czech Republic, the "big three" banks are Česká spořitelna, ČSOB and KB. ::: ## Levels of Assurance (LoA) Czech Bank iD supports **Level of Assurance (LoA) 3** with multi-factor authentication. This means that end-users must always use two independent verification factors, even if a lower LoA is requested. ## User journey with Bank iD End-users wanting to authenticate with Czech Bank iD typically follow these steps: 1. The user chooses their bank. 2. The user logs in to their bank's website in the same way as they normally log in to their online banking. 3. The user confirms their login with a second factor, either in the bank's mobile application or by entering a code they received by text message. 4. The user agrees that the bank will transfer selected personal data to the service provider (your application). 5. The user identity is verified. ## End-user personal data End-users that successfully complete authentication sessions with your application through Czech Bank iD agree to sharing their personal data with you. You rely on this information to verify the identity of new users and authenticate existing users. The data you can access depends on your plan and use case. You can learn more about the data available through Czech Bank iD in the [Attributes reference](/identity-methods/cz-bankid/attributes-reference/index.mdx) documentation. ## Additional resources Learn more about Czech Bank iD from official sources: * [Official website](https://bankid.cz/) * [Demo site](https://demo.bankid.cz/) (Requires Bank iD credentials) * [UX style guide](https://ux.bankid.cz/styleguide/ui-ukazky) ## Next steps When you are ready to start integrating with Czech Bank iD in the Signicat eID and Wallet Hub, follow our guides: * [**Test it out**](/identity-methods/cz-bankid/test/): Test it out with your sandbox account before you start integrating * [**Integration guides**](/identity-methods/cz-bankid/integration/): Learn how to set up, configure and test the integration --- ## Czech Bank iD attributes in Authentication REST API This page contains information about the user attributes that you can request and retrieve from Czech Bank iD when using the [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) as an authentication protocol. ## Attributes table :::CustomTable{columnWidths="20% 20% 20% 40%"} | Attribute code | Attribute name | Example | Description | | :--- | :--- | :--- | :--- | | `firstName` | First name | `John` | The user's first name. | | `lastName` | Last name | `Doe` | The user's last name. | | `fullName` | Full name | `John Robert Doe` | The user's full name. | | `middleName` | Middle name | `Robert` | The user's middle name(s). | | `gender` | Gender | `male` | The gender of the user. | | `dateOfBirth` | Date of birth | `1985-06-15` | The user's date of birth in `YYYY-MM-DD` format. | | `company` | Company | `Signicat AS` | The organization or company associated with the user. | | `street` | Street | `Munkegata` | The street address of the user. | | `houseNumber` | House number | `26` | The house number of the address. | | `houseNumberSuffix` | House number suffix | `B` | The house number suffix. | | `city` | City | `Trondheim` | The city of the address. | | `region` | Region | `Trøndelag` | The state, region, or province of the address. | | `postalCode` | Postal code | `7011` | The postal/zip code of the address. | | `country` | Country | `Norway` | The country of the address. | | `fullAddress` | Full address | `Munkegata 26B, 7011 Trondheim, Norway` | The complete formatted address of the user. | | `phoneNumber` | Phone number | `+4799999999` | The phone number of the user. | | `ninValue` | National ID number | `15068512345` | The national identification number value. | | `ninType` | National ID type | `social_security_number` | The type of national identification number. | | `ninIssuingCountry` | National ID issuing country | `NO` | The issuing country of the national identification number. | ::: ## Examples ### Request example To create a session using the Authentication REST API, you send a POST request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint of the Authentication REST API. This is `https://api.signicat.com/auth/rest/sessions`. You define the parameters of the session in the payload of the request. For example: ```json { "allowedProviders": [ "bankid-cz" ], "flow": "redirect", "requestedAttributes": [ "address", "bankidCzIdCard", "bankidCzLimitedLegalCapacity", "bankidCzPaymentAccounts", "bankidCzPep", "bankidCzTitlePrefix", "bankidCzTitleSuffix", "bankidCzUpdatedAt", "bankidCzVerificationProcess", "bankidCzVerificationTrustFramework", "countryOfBirth", "dateOfBirth", "18OrOlder", "email", "firstName", "gender", "lastName", "maritalStatus", "middleName", "name", "nationality", "nin", "phoneNumber", "placeOfBirth", "idpId" ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "requestDomain": "" } ``` ### Response example The following is an example of a response showing the end-user information attributes: ```json { "id": "ab...d7-b5cb-402e-a989-d...57", "accountId": "a-spge-zRW...XB", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=0ef7112f-d292-b042-a289-e42b66f02424&transactionId=3f7ea0c8-97ae-c547-ad5f-a62492ceb0a2", "status": "SUCCESS", "provider": "bankid-cz", "subject": { "id": "2chXmU2kWsMJWZ4x-mCxcbiaKSkSVNDiglqp8nBIP5s=", "idpId": "fed17912-aa8b-4f88-8c0f-9eb2b909d07f", "name": "Jan Novák", "firstName": "Jan", "lastName": "Novák", "dateOfBirth": "1970-08-01", "email": "J.novak@example.com", "nin": { "value": "7008018556", "issuingCountry": "CZ", "type": "PERSON" }, "placeOfBirth": "Praha 4", "countryOfBirth": "CZ", "nationality": "AT, CZ", "maritalStatus": "MARRIED", "bankidCzPep": "false", "bankidCzLimitedLegalCapacity": "false", "bankidCzPaymentAccounts": "CZ9530300000000999999998, CZ4830300000000999999971", "bankidCzUpdatedAt": "1622543116", "bankidCzIdCard": "123456789", "bankidCzVerificationProcess": "45244782", "bankidCzVerificationTrustFramework": "cz_aml", "phoneNumber": "+420123456789", "gender": "M", "address": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315", "addressFormatted": { "FullAddress": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315", "Street": "Dlouhá", "HouseNumber": "609", "City": "Praha", "PostalCode": "11000", "Country": "CZ" } }, "callbackUrls": { "success": "https://example.com:443/success?sessionId=aba31ed7-b5cb-402e-a989-dcf1d0f7f557", "abort": "https://example.com:443/abort?sessionId=aba31ed7-b5cb-402e-a989-dcf1d0f7f557", "error": "https://example.com:443/error?sessionId=aba31ed7-b5cb-402e-a989-dcf1d0f7f557" }, "environment": { "ipAddress": "192.0.2.0", "userAgent": "userAgent" }, "loa": "high", "allowedProviders": [ "bankid-cz" ], "language": "en", "flow": "redirect", "requestedAttributes": [ "address", "bankidCzIdCard", "bankidCzLimitedLegalCapacity", "bankidCzPaymentAccounts", "bankidCzPep", "bankidCzTitlePrefix", "bankidCzTitleSuffix", "bankidCzUpdatedAt", "bankidCzVerificationProcess", "bankidCzVerificationTrustFramework", "countryOfBirth", "dateOfBirth", "18OrOlder", "email", "firstName", "gender", "lastName", "maritalStatus", "middleName", "name", "nationality", "nin", "phoneNumber", "placeOfBirth", "idpId" ], "sessionLifetime": 1200, "expiresAt": "2025-04-30T10:38:50.6756621+00:00" } ``` --- ## Czech Bank iD attributes in OIDC This page contains information about the user attributes that you can request and retrieve from Czech Bank iD when using [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) as an authentication protocol. ## Attributes table Czech Bank iD provides the following data: :::CustomTable{columnWidths="10% 10% 10% 60%"} | Scope | OIDC Claim | Example | Description | | :------------------ | :---------------------- | :---------------------------------- | :---------- | | `idp-id` | `idp_id` | fed1791..9d07f | A hashed unique identifier of the subject of the user. | | `profile` | `name` | Jan Novák | The user's full name. | | `profile` | `given_name` | Jan | The user's first name. | | `profile` | `family_name` | Novák | The user's last name. | | `profile` | `middle_name` | Karel | The user's middle name, if available. | | `profile` | `birthdate` | 1990-05-20 | The user's date of birth in `YYYY-MM-DD` format. | | `profile` | `gender` | male | The user's gender. | | `name` | `name` | Jan Novák | The user's full name. | | `name` | `given_name` | Jan | The user's first name. | | `name` | `family_name` | Novák | The user's last name. | | `name` | `middle_name` | Karel | The user's middle name, if available. | | `date-of-birth` | `birthdate` | 1990-05-20 | The user's date of birth in `YYYY-MM-DD` format. | | `gender` | `gender` | male | The user's gender. | | `nationality` | `place_of_birth` | Brno | The city or place where the user was born. | | `nationality` | `country_of_birth` | CZ | The country where the user was born (ISO 3166-1 alpha-2 code). This means two letters in upper case. | | `nationality` | `nationality` | CZ | The user's nationality (ISO 3166-1 alpha-2 code). | | `address` | `address` | PERMANENT_RESIDENCE, Dlouhá, 2, 609, 11a, Praha, Pankrác, 11000, CZ, 21722315 | The user's registered address. Address is made up of: `type`, `street`, `buildingapartment`, `streetnumber`, `evidencenumber`, `city`, `cityarea`, `zipcode`, `country`, `ruian_reference`, where: `type`: Type of address element. One of: `PERMANENT_RESIDENCE`, `SECONDARY_RESIDENCE`, `UNKNOWN`. `street`: Street name. `buildingapartment`: Address land registry number.`streetnumber`: Additional address house number. `evidencenumber`: Optional. House registration number. `city`: City name. `cityarea`: Optional. City area name. `zipcode`: ZIP code. `country`: Country code (ISO 3166-1 alpha-2). `ruian_reference`: Address reference to the register of territorial identification, addresses and real estate. | | `nin` | `nin` | `{`` "value": "7008018556",`` "issuingCountry": "CZ",`` "type": "PERSON"``}` | National identity number object, where: `value`: The user's national identification number. `issuingCountry`: The issuing country of the national identity. `type`: The type of national identity number. | | `phone` | `phone_number` | +420123456789 | The user's phone number, including the country code. | | `email` | `email` | j.novak@email.com | The user's email address. | | `eighteen-or-older` | `eighteen_or_older` | true | Indicates whether the user is 18 years or older. | | `marital-status` | `marital_status` | MARRIED | The user's marital status. One of: `COHABITATION`, `MARRIED`, `DIVORCED`, `REGISTERED_PARTNERSHIP`, `REGISTERED_PARTNERSHIP_CANCELED`, `WIDOWED`, `SINGLE`, `UNKNOWN`. | | `bankid-cz-extra` | `bankid_cz_majority` | true | Indicates whether the user has passed the age of majority, the threshold of legal adulthood as recognised or declared in law. | | `bankid-cz-extra` | `bankid_cz_pep` | false | Indicates whether the user is a politically exposed person (PEP): a person entrusted with a prominent public function and at higher risk for bribery and corruption due to their position. | | `bankid-cz-extra` | `bankid_cz_limited_legal_capacity` | false | Indicates whether the user has limited legal capacity. | | `bankid-cz-idcards` | `bankid_cz_id_card` | 98765432 | The number of the user's ID card. | | `bankid-cz-title` | `bankid_cz_title_prefix` | Ing. | The user's title prefix, such as an academic or professional title. | | `bankid-cz-title` | `bankid_cz_title_suffix` | Ph.D. | The user's title suffix, such as an academic or professional designation. | | `bankid-cz-updated` | `bankid_cz_updated_at` | 1622543116 | The date and time when the user's data was last updated. The value is a Unix timestamp to encode the seconds passed since 1970-01-01 00:00:00 UTC. | | `bankid-cz-bank` | `bankid_cz_payment_accounts` | CZ9530300000000999999998 | The user's payment account numbers in CZ IBAN format. May return multiple space-separated entries. | | `bankid-cz-aml` | `bankid_cz_verification_trust_framework` | cz_aml | Applies to AML verification only. The trust framework governing the identity verification process and the identity assurance level. To request this attribute, you must set `profile.verification` to "Required" in the Czech Bank iD Dashboard. | | `bankid-cz-aml` | `bankid_cz_verification_process` | 45244782 | Applies to AML verification only. The identification number of the bank (financial institution) that carried out the identification process as reported in the registered entities of the [CNB JERRS](https://www.cnb.cz/cnb/jerrs_en). To request this attribute, you must set `profile.verification` to "Required" in the Czech Bank iD Dashboard. | ::: :::warning AML verification settings If you set `profile.verification` to **Required** when configuring your app in the Czech Bank iD Dashboard, then you must specify `bankid-cz-aml` in your authentication request. ::: ## Examples When connecting with OIDC, you specify the scopes in the authentication request. After the end-user verifies their identity, consents to sharing their data and the flow is complete, you can retrieve the claims in the ID Token or through the UserInfo endpoint. Below, you find examples of requests and responses to gain insight into the exchange of user information that occurs during an authentication process with OIDC. ### Request example To trigger an authentication, you build an OIDC request like: ```http https:///auth/open/connect/authorize? &client_id= &response_type=code &redirect_uri= &state=xyz123 &scope=openid%20profile%20nin%20address%20email%20phone%20gender%20date-of-birth%20eighteen-or-older%20nationality%20marital-status%20idp-id%20name%20bankid-cz-extra%20bankid-cz-idcards%20bankid-cz-title%20bankid-cz-bank%20bankid-cz-aml &acr_values=idp:bankid-cz &prompt=login &nonce=abc456 ``` Note the following request parameters shown in the example above: - `scope`: The scope specifies the set of claims that the client application is requesting from Czech Bank iD. - `acr_values`: The Authentication Context Class Reference (ACR) values determine the type or level of authentication required. To show only Czech Bank iD, as a provider for authentication, pass `idp:bankid-cz`. :::info What happens next? 1. The user is redirected to CZ Bank iD for authentication. 2. If successful, the authorization code is sent to the `redirect_uri`. 3. You exchange the authorization code for an ID token and access token. ::: ### Response example Below, you find an example of a response obtained from an identity verification flow with Czech Bank iD. Scopes in request: `openid`, `profile`, `idp-id`, `email`, `phone`, `nationality`, `nin`, `bankid-cz-extra`, `bankid-cz-idcards`, `bankid-cz-title`, `bankid-cz-bank`, `bankid-cz-aml` Example of **ID token** in response: ```json { "iss":"https:///auth/open", "nbf":1726046529, "iat":1726046529, "exp":1726047129, "aud":"", "amr":[ "external" ], "at_hash":"_T539pqKJTOovx1xVyMnKA", "sid":"783EFB56CEE40C1FA95F0543535B6E4E", "sub":"X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=", "auth_time":1726046523, "idp":"bankid-cz", "idp_id":"fed17912-aa8b-4f88-8c0f-9eb2b909d07f", "sandbox":true } ``` :::tip ID Token The ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, edit the **ID Token User data** field in the **Advanced > Security** tab of your OIDC client configuration in the [Signicat Dashboard](https://dashboard.signicat.com/oidc-clients/). ::: Example of a response from the **UserInfo** endpoint: ```json { "sub": "987654321", "idp_id": "bankid-cz", "name": "Josef Dvořák", "given_name": "Josef", "family_name": "Dvořák", "middle_name": "Karel", "birthdate": "1990-05-20", "gender": "male", "place_of_birth": "Brno", "country_of_birth": "CZ", "nationality": "CZ", "address": { "street_address": "Náměstí Republiky 5", "postal_code": "11000", "locality": "Praha", "country": "CZ" }, "nin": { "value": "8505051234", "issuingCountry": "CZ", "type": "PERSON" }, "phone_number": "+420601234567", "email": "josef.dvorak@example.cz", "eighteen_or_older": true, "marital_status": "married", "bankid_cz_title_prefix": "Ing.", "bankid_cz_title_suffix": "Ph.D.", "bankid_cz_pep": false, "bankid_cz_limited_legal_capacity": false, "bankid_cz_payment_accounts": "CZ9530300000000999999998, CZ4830300000000999999971", "bankid_cz_updated_at": "1622543116", "bankid_cz_id_card": "123456789", "bankid_cz_verification_trust_framework": "cz_aml", "bankid_cz_verification_process": "45244782" } ``` --- ## Czech Bank iD attributes in SAML 2.0 This page contains information about the user attributes that you can request and retrieve from Czech Bank iD when using [SAML 2.0](/docs/eid-hub/saml-2-0/) as an authentication protocol. ## Attributes table :::CustomTable{columnWidths="20% 20% 20% 40%"} | Attribute code | Attribute name | Example | Description | | :--- | :--- | :--- | :--- | | `firstName` | First name | `John` | The user's first name. | | `lastName` | Last name | `Doe` | The user's last name. | | `fullName` | Full name | `John Robert Doe` | The user's full name. | | `middleName` | Middle name | `Robert` | The user's middle name(s). | | `gender` | Gender | `male` | The gender of the user. | | `dateOfBirth` | Date of birth | `1985-06-15` | The user's date of birth in `YYYY-MM-DD` format. | | `company` | Company | `Signicat AS` | The organization or company associated with the user. | | `street` | Street | `Munkegata` | The street address of the user. | | `houseNumber` | House number | `26` | The house number of the address. | | `houseNumberSuffix` | House number suffix | `B` | The house number suffix. | | `city` | City | `Trondheim` | The city of the address. | | `region` | Region | `Trøndelag` | The state, region, or province of the address. | | `postalCode` | Postal code | `7011` | The postal/zip code of the address. | | `country` | Country | `Norway` | The country of the address. | | `fullAddress` | Full address | `Munkegata 26B, 7011 Trondheim, Norway` | The complete formatted address of the user. | | `phoneNumber` | Phone number | `+4799999999` | The phone number of the user. | | `ninValue` | National ID number | `15068512345` | The national identification number value. | | `ninType` | National ID type | `social_security_number` | The type of national identification number. | | `ninIssuingCountry` | National ID issuing country | `NO` | The issuing country of the national identification number. | ::: ## Examples ### Metadata document The example below shows a Service Provider (SP) metadata document to connect to Czech Bank iD and request the attributes: `idpId`, `address`,`bankidCzIdCard`, `bankidCzLimitedLegalCapacity`, `bankidCzPaymentAccounts`, `bankidCzPep`, `bankidCzTitlePrefix`, `bankidCzTitleSuffix`, `bankidCzUpdatedAt`, `countryOfBirth`, `dateOfBirth`, `18OrOlder`, `email`, `firstName`, `gender`, `lastName`, `maritalStatus`, `middleName`, `name`, `nationality`, `nin`, `phoneNumber`, `placeOfBirth`, `bankidCzVerificationTrustFramework`, `bankidCzVerificationProcess`. ```xml X509_CERTIFICATE All attributes ``` ### Request example SAML 2.0 request example: ```xml SAML Example SP ``` ### Response example SAML 2.0 response example: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml gjhtHxMFfm-2bn-YaZ6mh2YfTL62z-EyU2AdnWbx3x4= ENTITY_ID fed17912-aa8b-4f88-8c0f-9eb2b909d07f PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315 Jan Novák Jan Novák J.novak@example.com male 1970-08-01 CZ true MARRIED 850321/1234 CZ PERSON CZ Brno +420123456789 123456789 false false Ing. Ph.D. CZ9530300000000999999998, CZ4830300000000999999971 2025-05-01T09:00:00Z cz_aml 45244782 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:ORGANISATION_IDENTIFICATION_NUMBER:entities:9713 ``` --- ## Attributes reference(Attributes-reference) When you integrate Czech Bank iD to verify the identity of users accessing your online services, you request and obtain personal information relevant to your use case. To discover what kind of information is available for a given authentication protocol, visit the respective pages listed below: - [Czech Bank iD attributes in OpenID Connect (OIDC)](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-oidc.mdx) - [Czech Bank iD attributes in the Signicat Authentication REST API](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-authentication-api.mdx) - [Czech Bank iD attributes in SAML 2.0](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-saml.mdx) The pages above also contain examples of requests and responses to help you understand the structure and format of the data. ## Step configuration Explore additional information about the data provided by Czech Bank iD. ### AML compliancy with profile verification Czech Bank iD provides bank-verified personal data to help you comply with Anti-Money Laundering (AML) regulations. The following attributes are available: - **Verification process**: Contains the company identification number of the bank that completed the physical identity verification process. - **Trust framework**: The AML framework governing the verification process (always `cz_aml`). If you have an AML-compliant contract with Czech Bank iD and want to request the attributes above, you must follow these steps: - Set `profile.verification` as **Required** when configuring your app in the Czech Bank iD Dashboard. - Specify *at least one* AML-specific attribute in your authentication request. These are: - [OpenID Connect (OIDC)](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-oidc.mdx): `bankid-cz-aml` - [Signicat Authentication REST API](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-authentication-api.mdx): `bankidCzVerificationProcess`, `bankidCzVerificationTrustFramework` - [SAML 2.0](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-saml.mdx): `bankidCzVerificationProcess`, `bankidCzVerificationTrustFramework` :::warning Important The authentication process fails and returns an error, if you only complete one of the steps above. ::: ### Sector identifier as subject Bank iD uses pairwise subject identifiers, therefore each end user has a unique subject (`sub`) identifier per sector identifier. :::info What is a sector identifier The sector identifier is the host address (domain) of the sector identifier URI, which hosts a JSON array with all the Redirect URIs used across all your apps. When no sector identifier URI is provided, then the sector identifier corresponds to Redirect URI (host address). ::: To have consistent subject identifiers across multiple apps with distinct Redirect URIs, you need to use a common sector identifier URI to unify the sector identifier of the apps. --- ## Czech Bank iD Czech Bank iD is an electronic identification (eID) method in the Czech Republic that can be used for identity verification, authentication and electronic signing of documents. :::note Facts about Czech Bank iD - Geographical coverage: Czech Republic. - Use cases: Onboarding, Authentication, Electronic Signing (on request). - Supported protocols: OIDC, Authentication REST API, SAML 2.0. - Devices: Mobile, desktop. - Key attributes: Name, national identity number, date of birth and [more](/identity-methods/cz-bankid/attributes-reference/). - LoA: Level of Assurance 3 (High). ::: If you want to read more high-level documentation about Czech Bank iD before you start the integration, see [About Czech Bank iD](/identity-methods/cz-bankid/about-cz-bankid.mdx). ## Get started * [**Test it out**](/identity-methods/cz-bankid/test/): Test it out with your sandbox account before you start integrating * [**Integration guide**](/identity-methods/cz-bankid/integration/): Learn how to set up, configure and test the integration ## Tell me more * [**About Czech Bank iD**](/identity-methods/cz-bankid/about-cz-bankid): High-level information about Czech Bank iD * [**Attributes reference**](/identity-methods/cz-bankid/attributes-reference/): Data, request and response examples per protocol ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Integration guide To integrate with Czech Bank iD in the Signicat eID and Wallet Hub, you need to: - Agree to contractual agreements with Signicat. - Set up your account in the Signicat Dashboard. - Implement a connection with an authentication protocol. ## How it works According to Czech law, companies that need to comply with AML regulations and want to use Bank iD for their online services must sign a direct contract with Czech Bank iD. Signicat offers alternative options to facilitate your integration process, whether with or without AML compliance. When integrating with Czech Bank iD through Signicat, you can choose between the following: - **Bring your own contract**: Applies to cases when you need to adhere to AML regulation. You must sign separate contracts with both Czech Bank iD and Signicat. - **Signicat as mediator**: Applies to all other cases. You only need to enter agreements with Signicat. ### Bring your own contract If you need to comply with AML regulations, you must enter into a direct contract with Czech Bank iD. You can find relevant information about pricing and contracts on the Bank iD website: - [Bank iD pricing](https://bankid.cz/firmy/cenik/) - [Bank iD contractual documents](https://bankid.cz/smluvni-dokumentace/) You can start integrating by following the steps in the [Set up Bank iD](/identity-methods/cz-bankid/integration/setup) guide. ### Signicat as a mediator When choosing Signicat as a mediator, we help you with the onboarding and integration process by configuring all the resources for you. You can test and integrate with Czech Bank iD in a sandbox environment by following the guides below. To go live in production, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. Our onboarding team will support you throughout the integration. ## Guides The guides below provide you with the steps required to integrate with Czech Bank iD. * [**Setup**](/identity-methods/cz-bankid/integration/setup): Set up your apps and accounts for Czech Bank iD * [**Implement**](/identity-methods/cz-bankid/integration/protocols/): Implement a connection with an authentication protocol --- ## Implement with the Signicat REST API This guide shows you how to authenticate end-users with Czech Bank iD, using the Signicat Authentication REST API with [redirect flow](#redirect-flow). :::info Want to learn more? To learn more about the Signicat Authentication REST API before integrating, see: - [Authentication REST API](/docs/eid-hub/authentication-api/) documentation. - [API Reference](/apis/eid-hub/) for endpoint descriptions. ::: ## Prerequisites 1. Follow the steps on the [Set up Czech Bank iD](/identity-methods/cz-bankid/integration/setup.mdx) page to establish a connection with Czech Bank iD. 2. Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). > Ensure that you set the **Authentication REST API** permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide. :::info Learn more about the Signicat Authentication REST API - [Authentication REST API](/docs/eid-hub/authentication-api/) for conceptual documentation. - [API Reference](/apis/eid-hub/) for endpoint descriptions. ::: ## Redirect flow This guide shows how to set up authentication using the *redirect flow*. The redirect flow allows you to pass an authorization URL to your end-users that they can open in a browser to follow an identity verification flow with Czech Bank iD. ### 1. Create a session #### Request To create a session using the Authentication REST API, you need to send a `POST` request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. **Enpoint URL**: `https://api.signicat.com/auth/rest/sessions` For example, you can build your request like this: ```http POST /auth/rest/sessions HTTP/1.1 Host: api.signicat.com Content-Type: application/json Accept: application/json Authorization: Bearer Content-Length: 735 { "flow": "redirect", "requestedAttributes": [ "idpId", "name", "firstName", "lastName", "middleName", "dateOfBirth", "gender", "placeOfBirth", "countryOfBirth", "nationality", "address", "nin", "phoneNumber", "email", "eighteenOrOlder", "maritalStatus", "bankidCzTitlePrefix", "bankidCzTitleSuffix", "bankidCzPep", "bankidCzLimitedLegalCapacity", "bankidCzPaymentAccounts", "bankidCzUpdatedAt", "bankidCzIdCard" ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" }, "allowedProviders": [ "bankid-cz" ], "language": "en" } ``` Note the following fields in the payload of the request: :::CustomTable{columnWidths="20% 20% 20% 40%"} | **Field** | **Required** | **Example value** | **Description** | | :-------------------| :------------| :-------------------| :-------------------------------| | `allowedProviders` | No | `["bankid-cz"]` | Specify `["bankid-cz"]` to show end-users only Czech Bank iD. To display all the eIDs enabled in your account, skip this. | | `flow` | Yes | `redirect` | MUST have the value `redirect`. | |`requestedAttributes`| Yes | `["firstName", "lastName", "name", "dateOfBirth", ...]` | The attributes you wish to get back from the authentication of the end-user. Learn more in the [Attributes reference](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-authentication-api.mdx). | ::: For more information about the "Create a new session" endpoint, see the [API Reference](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) description. :::note AML verification Czech Bank iD offers flows for compliance with Anti-Money Laundering (AML) laws and regulations. Learn more about the data attributes for AML in the [Attributes reference overview](/identity-methods/cz-bankid/attributes-reference/#aml-compliancy-with-profile-verification) page. ::: #### Response After you create a session, you receive a response with a summary of your request, a unique ID for the process and an `authenticationUrl`. Here is an example response: ```json { "id": "c99e17e2-b124-f549-a88c-408f8e555d31", "accountId": "", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31", "status": "CREATED", "callbackUrls": { "success": "https://example.com/success?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31", "abort": "https://example.com/abort?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31", "error": "https://example.com/error?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31" }, "allowedProviders": [ "bankid-cz" ], "language": "en", "flow": "redirect", "requestedAttributes": [ "address", "bankidCzIdCard", "bankidCzLimitedLegalCapacity", "bankidCzPaymentAccounts", "bankidCzPep", "bankidCzTitlePrefix", "bankidCzTitleSuffix", "bankidCzUpdatedAt", "countryOfBirth", "dateOfBirth", "eighteenOrOlder", "email", "firstName", "gender", "idpId", "lastName", "maritalStatus", "middleName", "name", "nationality", "nin", "phoneNumber", "placeOfBirth" ], "sessionLifetime": 1200, "expiresAt": "2025-04-30T12:43:22.0805822+00:00" } ``` ### 2. End-user authentication Now, your application can redirect the end-user to the `authenticationUrl` you obtained in the response. This is a unique URL that allows the end-user to perform authentication in the context of the session you just created. #### User journey By opening the authentication URL in the browser, end-users can follow an authentication flow with Czech Bank iD. You can preview what the flow looks like in the [Test it out](/identity-methods/cz-bankid/test.mdx) page. When the end-user completes the authentication flow, they are automatically redirected to the `callbackUrls` according to the outcome of the authentication. ### 3. Get the session status During the authentication process, you can monitor the status of the session to track whether the flow has started, failed or completed. Responses from successful authentications contain the end-user personal data. #### Request To get the status of a session, you need to send a `GET` request to the [Get session status](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) endpoint. You can find the session `id` value in the response you received when you created the session. ```http GET /auth/rest/sessions/{SESSION_ID} HTTP/1.1 Host: api.signicat.com Accept: application/json Authorization: Bearer ``` In the response example above, substitute the `SESSION_ID` with the value of the `id` you received in the response after creating the session. The value of the `id` is `c99e17e2-b124-f549-a88c-408f8e555d31` so the request would be `https://api.signicat.com/auth/rest/sessions/c99e17e2-b124-f549-a88c-408f8e555d31`. #### Response The response contains a `status` field with up-to-date information about the status of a session. Depending on the outcome of an authentication, the session can be in any of these states: `CREATED`, `SUCCESS`, `ERROR`, `ABORT`, `CANCELLED`, `WAITING_FOR_USER`, `EXPIRED`, `INVALID`. For more information about the "Get session status" endpoint, see the [API Reference](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) description. #### Review the response When the end-user authenticates successfully, you receive a response with status: `SUCCESS`. Then, you can retrieve personal data of the user in the `subject` field of the JSON response. For example: ```json { "id": "c99e17e2-b124-f549-a88c-408f8e555d31", "accountId": "", "authenticationUrl": "https:///broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31", "status": "SUCCESS", "provider": "bankid-cz", "subject": { "id": "2chXmU2kWsMJWZ4x-mCxcbiaKSkSVNDiglqp8nBIP5s=", "idpId": "fed17912-aa8b-4f88-8c0f-9eb2b909d07f", "name": "Jan Novák", "firstName": "Jan", "lastName": "Novák", "dateOfBirth": "1970-08-01", "email": "J.novak@example.com", "nin": { "value": "7008018556", "issuingCountry": "CZ", "type": "PERSON" }, "placeOfBirth": "Praha 4", "countryOfBirth": "CZ", "nationality": "AT, CZ", "maritalStatus": "MARRIED", "bankidCzPep": "false", "bankidCzLimitedLegalCapacity": "false", "bankidCzPaymentAccounts": "CZ9530300000000999999998, CZ4830300000000999999971", "bankidCzUpdatedAt": "1622543116", "bankidCzIdCard": "123456789", "phoneNumber": "+420123456789", "gender": "M", "address": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315", "addressFormatted": { "FullAddress": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315", "Street": "Dlouhá", "HouseNumber": "609", "City": "Praha", "PostalCode": "11000", "Country": "CZ" } }, "callbackUrls": { "success": "https://example.com:443/success?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4", "abort": "https://example.com:443/abort?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4", "error": "https://example.com:443/error?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4" }, "environment": { "ipAddress": "192.0.2.0", "userAgent": "userAgent" }, "loa": "high", "allowedProviders": [ "bankid-cz" ], "language": "en", "flow": "redirect", "requestedAttributes": [ "address", "bankidCzIdCard", "bankidCzLimitedLegalCapacity", "bankidCzPaymentAccounts", "bankidCzPep", "bankidCzTitlePrefix", "bankidCzTitleSuffix", "bankidCzUpdatedAt", "countryOfBirth", "dateOfBirth", "eighteenOrOlder", "email", "firstName", "gender", "idpId", "lastName", "maritalStatus", "middleName", "name", "nationality", "nin", "phoneNumber", "placeOfBirth" ], "sessionLifetime": 1200, "expiresAt": "2025-04-30T13:15:01.9071912+00:00" } ``` In the response object, you also find the eID (see `provider`) that the end-user chose for authentication. This can be useful when more than one eID is active in your Signicat account. :::note Success! You have now completed an authentication flow with Czech Bank iD using the Signicat Authentication REST API. ::: ## UX considerations To use the Czech Bank iD buttons, texts, logos and other graphic elements correctly in your applications, you need to follow the UX style guide at [https://ux.bankid.cz/](https://ux.bankid.cz/). ## Next steps Continue your journey with more Czech Bank iD guides: * [**Attributes reference**](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-authentication-api): Attributes reference and data for Czech Bank iD Dive deeper into the Signicat Authentication REST API: * [**Authentication REST API documentation**](/docs/eid-hub/authentication-api/): Find out more about the Signicat Authentication REST API. * [**Authentication REST API reference**](/apis/eid-hub/): Discover the endpoints of the Authentication REST API --- ## Implement The guides below provide you with the steps required to create your Czech Bank iD connection, using your chosen authentication protocol. * [**Implement with OIDC**](/identity-methods/cz-bankid/integration/protocols/oidc): Integrate using OpenID Connect * [**Implement with REST API**](/identity-methods/cz-bankid/integration/protocols/authentication-rest-api): Integrate using Signicat Authentication REST API * [**Implement with SAML 2.0**](/identity-methods/cz-bankid/integration/protocols/saml-2-0): Integrate using SAML 2.0 --- ## Implement with OIDC This guide shows you how to implement a connection with OpenID Connect (OIDC) for Czech Bank iD. :::note Before you begin Before starting your OIDC integration with Czech Bank iD, make sure to have [set up Czech Bank iD](/identity-methods/cz-bankid/integration/setup.mdx). ::: ## Add an OIDC client An OIDC client allows your application to authenticate users with Czech Bank iD as a provider using standardised, secure OAuth 2.0 protocols. When you register an OIDC client application, you receive a client ID. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/). 2. Select **Create/Add client**. 3. Enter a name for the client. 4. In **Primary grant type**, select the grant type (authentication flow) to use for this client. :::tip Choosing a grant type The **Authorization Code flow** is recommended for most cases. Learn more about supported flows in the generic [OIDC implementation](/docs/eid-hub/oidc/oidc-implementation/) guide and the [OAuth 2.0 specification](https://oauth.net/2/grant-types/). ::: 5. In the **Redirect URI** field, enter the URL where to redirect the end-user after authentication. You can always edit and add more URIs later. 6. In the **Scope** field, enter the scopes you want for this client. `openid` is mandatory. Find out what scopes are supported in the [Attributes reference](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-oidc.mdx). :::tip Scopes and personal data Scopes encode what personal information you request from your end-users. Your billing bundle with Signicat determines what scopes are available. ::: 7. Select **Create** to create the OIDC client. #### Add a client secret Depending on the type of your application, you may want to add a client secret. To do this: 1. In the menu for the client, go to the **Secrets** tab and select **Add secret**. 2. Enter a name for your client secret and select **Create**. 3. Copy your new client secret and store it safely. :::warning Important Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one. ::: :::note PKCE Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the [eID and Wallet Hub documentation](/docs/eid-hub/oidc/advanced-security/proof-key-for-code-exchange-pkce.mdx). ::: ## OIDC authentication flow An authentication flow with OIDC typically involves the following steps: 1. You build the authentication request with the appropriate parameters. 2. Redirect the user to the authorization endpoint. 3. User authenticates with Czech Bank iD. 4. After successful authentication, the provider sends the user to the Redirect URI. 5. At the same time, your application receives the authorization code and the state. 6. Your backend exchanges the code for tokens: ID token, access token and refresh token (optional). 7. You validate the ID token before establishing a session. 8. Optionally, you retrieve additional information through the `userInfo` endpoint. Below, you find instructions to complete an authentication flow with Czech Bank iD. ### Build the authentication request To begin an authentication flow, design your application to build an authentication URI which points to the authorization (`authorize`) endpoint. Then, you direct the end-user to the authentication URI in a browser, where the end-user can log in by choosing their bank for authentication with Czech Bank iD. Your application should send an HTTPS `GET` request with the appropriate URI parameters. Here is an example of an authentication URI with OIDC: ```sh https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &state=1599045135410-jFe &scope=openid%20profile%20nin%20address%20email%20phone%20gender%20date-of-birth%20eighteen-or-older%20nationality%20marital-status%20idp-id%20name%20bankid-cz-extra%20bankid-cz-idcards%20bankid-cz-title%20bankid-cz-bank &acr_values=idp:bankid-cz &prompt=login &nonce=1599046102647-dv4 ``` You can find the base URL of your `authorization_endpoint` in the discovery document of your OIDC client available in the [Signicat Dashboard](https://dashboard.signicat.com/oidc-clients/) under "Well-Known URL for client". The above example uses the following parameters: - `client_id`: The OIDC client you created in the Signicat Dashboard. - `response_type`: The grant type (flow). For the authorization code flow, use `code`. - `redirect_uri`: The Redirect URI where to send the end-user after authentication. - `state` A random string to prevent cross-site request forgery (CSRF). Verify it when the user is redirected back to your app. - `scope`: A space-delimited list of scopes to indicate what personal data to request. Find out what scopes are supported with Czech Bank iD in the [Attributes reference](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-oidc.mdx). - `acr_values=idp:bankid-cz`: Optional. ACR values specifies aspects such as assurance level or identity provider. In this example, `idp:bankid-cz` forces authentication with Czech Bank iD. - `prompt=login`: Optional. Forces the login screen to be shown, even if the user is already authenticated. - `nonce`: A cryptographically random string used to associate the request with the returned ID token. Helps prevent replay attacks and must be validated after login. You can find additional authentication request query parameters in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). :::tip Important The values you specify in the query parameters must match the values in the configuration of your OIDC client in the Dashboard. ::: :::note AML verification Czech Bank iD offers flows for compliance with Anti-Money Laundering (AML) laws and regulations. Learn more about the data attributes for AML in the [Attributes reference overview](/identity-methods/cz-bankid/attributes-reference/#aml-compliancy-with-profile-verification) page. ::: ### End-user authentication To authenticate with Czech Bank iD, end-users must authenticate with their bank and consent to share their personal data with you in the confirmation screen. You can view an example of end-user authentication flow with Czech Bank iD in the [Test it out](/identity-methods/cz-bankid/test.mdx) page. After successful authentication, the authorization server redirects the end-user back to the `redirect_uri`. The response message contains the authorization code and state in the query string. This may vary depending on the authentication flow. Now, you can retrieve the end-user data by exchanging the authorization code in the server response for an access token that includes the ID token (where the data is stored). The steps are explained below. ### Server response Example of the server response URI after the end-user authentication: ```sh https://? code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1 &scope=openid%20profile%20nin%20address%20email%20phone%20gender%20date-of-birth%20eighteen-or-older%20nationality%20marital-status%20idp-id%20name%20bankid-cz-extra%20bankid-cz-idcards%20bankid-cz-title%20bankid-cz-bank &state=1599045135410-jFe &session_state=PJl854GXgavBXj1-JRlfSvwkh9hpraImao2fvYDTDwE.A6AB53401320A51C5D61F205FE29468B &iss=https%3A%2F%2F%2Fauth%2Fopen ``` Your application should check that the state in the redirect matches the original `state` sent in the authentication request to mitigate CSRF and other related attacks. The `code` holds the authorization code generated by the authorization server. You use this code in the request to the token endpoint to obtain an access token and the ID token. ### Obtain the access token Your application can now exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS `POST` request to the `token` endpoint of the authorization server. **Example token request** ```http POST /auth/open/connect/token HTTP/1.1 Host: Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ== Content-Type: application/x-www-form-urlencoded grant_type= redirect_uri= code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1 code_verifier=oQDZ3uPQn...W7U ``` **Example token response** ```http HTTP/1.1 200 OK Content-Type: application/json { "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5", "token_type": "Bearer", "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g", "expires_in": 3600, "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg" } ``` ### ID token An ID token is a JWT that looks like `eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA`. :::details What is a JWT? A JSON Web Token (JWT) consists of three parts separated by dots (`.`), which correspond to: - Header - Payload - Signature A JWT typically looks like: `xxxxx.yyyyy.zzzzz` ::: The decoded payload (data) part of the ID token for Czech Bank iD would then look like: ```json { "iss": "https:///auth/open", "sub": "987654321", "aud": "", "nbf": 1712237928, "exp": 1712256000, "iat": 1712252400, "nonce": "abc456", "idp_id": "bankid-cz", "name": "Josef Dvořák", "given_name": "Josef", "family_name": "Dvořák", "middle_name": "Karel", "birthdate": "1990-05-20", "gender": "male", "place_of_birth": "Brno", "country_of_birth": "CZ", "nationality": "CZ", "address": { "street_address": "Náměstí Republiky 5", "postal_code": "11000", "locality": "Praha", "country": "CZ" }, "nin": { "value": "8505051234", "issuingCountry": "CZ", "type": "PERSON" }, "phone_number": "+420601234567", "email": "josef.dvorak@example.cz", "eighteen_or_older": true, "marital_status": "married", "bankid_cz_title_prefix": "Ing.", "bankid_cz_title_suffix": "Ph.D.", "bankid_cz_pep": false, "bankid_cz_limited_legal_capacity": false, "bankid_cz_payment_accounts": [ { "IBAN": "CZ6508000000000000123456" } ], "bankid_cz_updated_at": "2024-03-15T10:15:30Z", "bankid_cz_id_card": { "type": "ID", "number": "98765432" } } ``` :::tip ID Token By default, the ID Token returns only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, go to your OIDC client configuration in the [Signicat Dashboard](https://dashboard.signicat.com/oidc-clients/) and edit the **ID Token User data** in the **Advanced > Security** tab. ::: #### UserInfo response The response examples below show user information retrieved from the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. :::details Example response UserInfo endpoint ```json { "name": "Josef Dvořák", "given_name": "Josef", "family_name": "Dvořák", "middle_name": "Karel", "birthdate": "1990-05-20", "gender": "male", "place_of_birth": "Brno", "country_of_birth": "CZ", "nationality": "CZ", "address": { "street_address": "Náměstí Republiky 5", "postal_code": "11000", "locality": "Praha", "country": "CZ" }, "nin": { "value": "8505051234", "issuingCountry": "CZ", "type": "PERSON" }, "phone_number": "+420601234567", "email": "josef.dvorak@example.cz", "eighteen_or_older": true, "marital_status": "married", "bankid_cz_title_prefix": "Ing.", "bankid_cz_title_suffix": "Ph.D.", "bankid_cz_pep": false, "bankid_cz_limited_legal_capacity": false, "bankid_cz_payment_accounts": [ { "IBAN": "CZ6508000000000000123456" } ], "bankid_cz_updated_at": "2024-03-15T10:15:30Z", "bankid_cz_id_card": { "type": "ID", "number": "98765432" } } ``` ::: --- :::note Success! You have now completed an authentication flow with Czech Bank iD. ::: ## UX considerations To use the Czech Bank iD buttons, texts, logos and other graphic elements correctly in your applications, you need to follow the UX style guide at [https://ux.bankid.cz/](https://ux.bankid.cz/). ## Next steps Continue your journey with more Czech Bank iD guides: * [**Attributes reference**](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-oidc): Scopes and claims for Czech Bank iD with OIDC Dive deeper into OIDC and improve your application with advanced security features: * [**Advanced OIDC implementation**](/docs/eid-hub/oidc/oidc-implementation): Learn about available flows, endpoints, claims, key rotation, security, error codes and more * [**Advanced security considerations**](/docs/eid-hub/oidc/advanced-security): Learn about advanced security measures like PKCE and encryption --- ## Implement with SAML 2.0 :::note Before you begin Before starting your SAML integration with Czech Bank iD, make sure to have [set up Czech Bank iD](/identity-methods/cz-bankid/integration/setup.mdx). ::: Get started with your SAML 2.0 integration with our guides: * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for authentication. * [**Implement a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection with Signicat. See what SAML parameters apply to Czech Bank iD: * [**Attributes reference**](/identity-methods/cz-bankid/attributes-reference/cz-bankid-attributes-saml): Attributes and examples for Czech Bank iD with SAML 2.0 ## UX considerations To use the Czech Bank iD buttons, texts, logos and other graphic elements correctly in your applications, you need to follow the UX style guide at [https://ux.bankid.cz/](https://ux.bankid.cz/). --- ## Set up Bank iD This page describes how to set up Czech Bank iD in the Signicat Dashboard. :::info About this documentation The instructions apply to you if you want to integrate: - In a sandbox environment. - In a production environment with a direct contract with Czech Bank iD (see Bring your own contract in the [How it works](/identity-methods/cz-bankid/integration/index.mdx#how-it-works) section). To go live in production with [Signicat as a mediator](/identity-methods/cz-bankid/integration/index.mdx#signicat-as-a-mediator) instead, you need to contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ## Get connection URIs To set up a connection between Signicat and Czech Bank iD, you first need to generate connection URIs that you later use to configure an app in the Czech Bank iD Dashboard. To generate connection URIs in the Signicat Dashboard, do the following: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn) 2. Select **+ Add new**. 3. From the list of eIDs, select **Czech Bank iD**. 4. In the configuration screen, select **Get URIs** to generate URIs based on your Signicat account. These are: - **Redirect URIs**: The address, pointing to your domain(s), where Czech Bank iD directs its response after authentication. Multiple URIs are generated when you have multiple domains in your account. Learn more about domains in the [documentation](/docs/dashboard/organisation-management/domains/). - **Sector Identifier URI**: Applies when using multiple Redirect URIs. Points to a list of all your Redirect URIs. - **JWKS URI**: Hosts the JSON web key set (JWKS) to communicate with Bank iD. 5. Copy the URIs. You will need them later in the process when configuring your app settings in the Czech Bank iD Dashboard. You may leave the Signicat Dashboard and continue with next step below. ## Create an app in the Czech Bank iD Dashboard After obtaining the connection URIs, you need to register on the Czech Bank iD Dashboard where you receive credentials that you later use in your Signicat account. To do this: 1. Go to [https://developer.bankid.cz/dashboard](https://developer.bankid.cz/dashboard). 2. If you don't have an account yet, select **Register** and follow the on-screen steps. 3. Once registered, log in to the Czech Bank iD Dashboard. 4. In the Dashboard, select **Create app**. 5. In the New app dialog, enter the name for your app. Optionally, you can upload a logo. 6. Select **Create app** to create the new app. After creating the app, you are redirected to the overview screen where you can manage your app configuration. To connect the Czech Bank iD app to your Signicat account, you must configure the app settings and obtain credentials that you later add in your Signicat account, as explained in the next sections. :::tip Environments In the Czech Bank iD Dashboard, you can configure two types of environments: - Sandbox: Allows you to test your connection. - Production: Requires that you sign a contract and create an organisation. ::: ### Create an organisation with Bank iD :::warning Production only This section applies if you want to integrate with Czech Bank iD in a production account. To test in sandbox, you may skip this section. ::: To go live in a production environment, you need to connect your app to an organisation. To do this you need to first sign a contract with Czech Bank iD by doing the following: 1. Log in to [https://developer.bankid.cz/dashboard](https://developer.bankid.cz/dashboard). 2. Select the app you want to configure. 3. In the left menu, navigate to **App management** > **App Settings**. 4. Under **Organization**, select **Create an organization**. 5. Fill in the **Request to sign a contract** form with you company details. Then, select **Send request** to apply for a contract. Czech Bank iD will contact you with information about your application. When ready, configure the production app and link it to your Signicat production account. ## Configure your app settings To set up a connection between Signicat and Czech Bank iD, you need to obtain credentials by configuring your app in the Czech Bank iD Dashboard. To do this for the app that you have previously created: 1. In the app overview, choose your environment (**Sandbox** or **Production**) under **Environments**. 2. Go to **Settings** to configure your environment. 3. Apply the following configuration settings: :::info 1. General application config Fill in the required fields with your company details. ::: :::info 2. Open ID Connect and OAuth2 settings - **Redirect URIs**: Enter the Redirect URI(s) that you previously generated in the Signicat Dashboard. These are: - *Sandbox*: `https:///idps/sandbox/bankid-cz/response`. For example, `https://example.sandbox.signicat.com/idps/sandbox/bankid-cz/response`. - *Production*: `https:///idps/bankid-cz/response`. For example, `https://example.signicat.com/idps/bankid-cz/response`. To add multiple Redirect URIs, enter all the Redirect URIs on separate rows and provide the Sector Identifier URI. - **Sector Identifier URI**: Optional. Only required when configuring multiple Redirect URIs. Enter the Sector Identifier URI that you previously generated in the Signicat Dashboard. These are: - *Sandbox*: `https:///idps/sandbox/bankid-cz/sector-identifier`. For example, `https://example.sandbox.signicat.com/idps/sandbox/bankid-cz/sector-identifier`. - *Production*: `https:///idps/bankid-cz/sector-identifier`. For example, `https://example.signicat.com/idps/bankid-cz/sector-identifier`. - **Notification URI**: Any valid URL works since notifications are not processed. For example, you may enter the URL of your Signicat domain. ::: :::info 3. Scopes Set the following scopes to: - `openid`: Required - `profile.verification`: Unused. Set to Required, if you need to comply with AML regulations. :::note AML verification Set `profile.verification` as **Required** if you want to perform AML verification. Note that you must always request the AML attributes in your authentication request. Learn more in the [Attributes reference](/identity-methods/cz-bankid/attributes-reference/#aml-compliancy-with-profile-verification). We recommend you set the other scopes to **Optional**. Any scope set to **Required** must also be configured in the Signicat Dashboard and specified in the authentication request. ::: :::info 4. Advanced Settings - **Authorization code flow**: ON - **Refresh token**: Optional - **Implicit flow**: OFF - **Token endpoint auth method**: Client Secret POST - **JWKS URI**: Enter the JWKS URI that you previously generated in the Signicat Dashboard. These are: - *Sandbox*: `https:///idps/sandbox/bankid-cz/jwks` - *Production*: `https:///idps/bankid-cz/jwks` - **Encrypt tokens**: ON - **Elliptic curve token encryption**: OFF - **Request URIs**: Empty ::: 4. Scroll to the bottom of the page, then select **Apply changes and generate credentials**. 5. Now, the Dashboard redirects you to the Credentials tab. Under **Credentials** > **Keys**, note the **Client ID** and **Client Secret** generated for your app. You need to copy and paste these credentials in the Signicat Dashboard configuration, as explained in the section below. ## Add Czech Bank iD in the Signicat Dashboard 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ## Test Czech Bank iD Once you have added Czech Bank iD to the list of available eIDs, you can test how it works for the end-user in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. At the top right, select **Test eIDs**. :::note Note If more than one eID is configured for the account, then a dialog with a list of configured methods is shown. You must select **Czech Bank iD** from this list. ::: 3. In the Czech Bank iD provider page, select the Bank IdP — this is a test bank. 4. In the Sandbox Inc. authentication site, select the demo account **JanN**. You can find a list of demo accounts in the bottom-right corner. Alternatively, enter the following credentials: - Name: `JanN` - Password: `password` 5. Select **Log in**. 6. Review the personal data requested for authentication. To confirm, scroll to the bottom and select **Potvrdit přístup** (Confirm access). Upon completion, you can review the list of attributes retrieved during authentication. ## Next steps: Implement You are now ready to implement your integration with an authentication protocol. The eID and Wallet Hub supports the following authentication protocols: - [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) - [SAML 2.0](/docs/eid-hub/saml-2-0/) - [Signicat's Authentication REST API](/docs/eid-hub/authentication-api/) You can build your integration with one of the protocols, by following the respective guide for Czech Bank iD: * [**Implement with OIDC**](/identity-methods/cz-bankid/integration/protocols/oidc): Integrate using OpenID Connect * [**Implement with REST API**](/identity-methods/cz-bankid/integration/protocols/authentication-rest-api): Integrate using Signicat Authentication REST API * [**Implement with SAML 2.0**](/identity-methods/cz-bankid/integration/protocols/saml-2-0): Integrate using SAML 2.0 --- ## Test it out This page shows you how to test out authentication with Czech Bank iD using the Signicat Dashboard. ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: :::tip Test in sandbox To test out the eID, you only need to set up a sandbox account. ::: ## Get connection URIs To set up a connection between Signicat and Czech Bank iD, you first need to generate connection URIs that you later use to configure an app in the Czech Bank iD Dashboard. To generate connection URIs in the Signicat Dashboard, do the following: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn) 2. Select **+ Add new**. 3. From the list of eIDs, select **Czech Bank iD**. 4. In the configuration screen, select **Get URIs** to generate URIs based on your Signicat account. These are: - **Redirect URIs**: The address, pointing to your domain(s), where Czech Bank iD directs its response after authentication. Multiple URIs are generated when you have multiple domains in your account. Learn more about domains in the [documentation](/docs/dashboard/organisation-management/domains/). - **Sector Identifier URI**: Applies when using multiple Redirect URIs. Points to a list of all your Redirect URIs. - **JWKS URI**: Hosts the JSON web key set (JWKS) to communicate with Bank iD. 5. Copy the URIs. You will need them later in the process when configuring your app settings in the Czech Bank iD Dashboard. You may leave the Signicat Dashboard and continue with next step below. ## Create an app in the Czech Bank iD Dashboard After obtaining the connection URIs, you need to register on the Czech Bank iD Dashboard where you receive credentials that you later use in your Signicat account. To do this: 1. Go to [https://developer.bankid.cz/dashboard](https://developer.bankid.cz/dashboard). 2. If you don't have an account yet, select **Register** and follow the on-screen steps. 3. Once registered, log in to the Czech Bank iD Dashboard. 4. In the Dashboard, select **Create app**. 5. In the New app dialog, enter the name for your app. Optionally, you can upload a logo. 6. Select **Create app** to create the new app. After creating the app, you are redirected to the overview screen where you can manage your app configuration. To connect the Czech Bank iD app to your Signicat account, you must configure the app settings and obtain credentials that you later add in your Signicat account, as explained in the next sections. :::tip Environments In the Czech Bank iD Dashboard, you can configure two types of environments: - Sandbox: Allows you to test your connection. - Production: Requires that you sign a contract and create an organisation. ::: ## Configure your app settings To set up a connection between Signicat and Czech Bank iD, you need to obtain credentials by configuring your app in the Czech Bank iD Dashboard. To do this for the app that you have previously created: 1. In the app overview, select **Sandbox** under **Environments**. 2. Go to **Settings** to configure your environment. 3. Apply the following configuration settings: :::info 1. General application config Fill in the required fields with your desired company details. ::: :::info 2. Open ID Connect and OAuth2 settings - **Redirect URIs**: Enter the Redirect URI(s) that you previously generated in the Signicat Dashboard. This is: `https:///idps/sandbox/bankid-cz/response`. For example, `https://example.sandbox.signicat.com/idps/sandbox/bankid-cz/response`. To add multiple Redirect URIs, press the Enter key and paste the URI. - **Sector Identifier URI**: Optional. Only required when configuring multiple Redirect URIs. Enter the Sector Identifier URI that you previously generated in the Signicat Dashboard. This is `https:///idps/sandbox/bankid-cz/sector-identifier`. For example, `https://example.sandbox.signicat.com/idps/sandbox/bankid-cz/sector-identifier`. - **Notification URI**: Any valid URL works since notifications are not processed. For example, the URL of your Signicat domain. ::: :::info 3. Scopes Make sure the following scopes are set to: - `openid`: Required - `profile.verification`: Unused We recommend you set the other scopes to **Optional**. Any scope set to **Required** must also be configured in the Signicat Dashboard and specified in the authentication request. ::: :::info 4. Advanced Settings - **Authorization code flow**: ON - **Refresh token**: Optional - **Implicit flow**: OFF - **Token endpoint auth method**: Client Secret POST - **JWKS URI**: Enter the JWKS URI that you previously generated in the Signicat Dashboard. This is `https:///idps/sandbox/bankid-cz/jwks`. - **Encrypt tokens**: ON - **Elliptic curve token encryption**: OFF - **Request URIs**: Empty ::: 4. Scroll to the bottom of the page, then select **Apply changes and generate credentials**. 5. Now, the Dashboard redirects you to the Sandbox Credentials tab. Under **Credentials** > **Keys**, note the **Client ID** and **Client Secret** generated for your app. You need to copy and paste these credentials in the Signicat Dashboard configuration, as explained in the section below. ## Add Czech Bank iD in the Signicat Dashboard 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ## Test Czech Bank iD Once you have added Czech Bank iD to the list of available eIDs, you can test how it works for the end-user in the Signicat Dashboard. To do this: 1. Go to **Signicat Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. At the top right, select **Test eIDs**. :::note Note If more than one eID is configured for the account, then a dialog with a list of configured methods is shown. You must select **Czech Bank iD** from this list. ::: 3. In the Czech Bank iD provider page, select the Bank IdP — this is a test bank. 4. In the Sandbox Inc. authentication site, select the demo account **JanN**. You can find a list of demo accounts in the bottom-right corner. Alternatively, enter the following credentials: - Name: `JanN` - Password: `password` 5. Select **Log in**. 6. Review the personal data requested for authentication. To confirm, scroll to the bottom and select **Potvrdit přístup** (Confirm access). Upon completion, you can review the list of attributes retrieved during authentication. ## User flow Below, you can preview how a typical user journey with Czech Bank iD looks like: ## Test users Czech Bank iD provides a list of test users for covering different authentication scenarios. You can find the test users in the Czech Bank iD Dashboard. To view the test users: 1. Log in to [https://developer.bankid.cz/dashboard](https://developer.bankid.cz/dashboard). 2. Select your app. 3. In the app overview, select **Sandbox** under **Environments**. Then, go to **Instructions**. 4. Select "List of test users for Sandbox" to download the list of users. The username is in the first row while the password for each user is always "password." ## Next steps After testing, you are ready to start integrating with Czech Bank iD through Signicat: * [**Integration guide**](/identity-methods/cz-bankid/integration/): Learn how to set up, configure and test the integration --- ## About DigiD ## Overview DigiD is an electronic identification method that allows access to public services and government websites in the Netherlands. Dutch citizens and residents with a BSN (Dutch citizen service number) can use DigiD to access online administration services, such as taxes, applying for allowances or benefits, or checking pension information. For service providers (you), DigiD gives certainty about the identity of end-users by returning the BSN. Note that the BSN is the only end-user information that DigiD delivers. DigiD is eIDAS-notified and can be used at many European public service providers. :::info DigiD Machtigen Signicat supports integrations with DigiD Machtigen (Authorisation), a service for citizens authorised to log in on behalf of another person. To implement DigiD Machtigen, you need to integrate with our [DigiD CombiConnect](/identity-methods/digid-combiconnect/) solution. ::: ## How it works You can find example videos on how DigiD works with and without the DigiD app in the [Tutorial videos for DigiD](https://www.digid.nl/en/help/tutorial-videos-digid) page. ## Login methods DigiD offers identity verification by means of a username and a password, and optionally an additional verification step with SMS or the DigiD mobile app. The Signicat integration supports identity verification with all these different credential methods. End-users can identify themselves using DigiD in one of the following different ways: - Username and password - SMS verification code - DigiD app - Identity card You may choose to require a certain method of authentication for end-users based on the level of security and data sensitivity that your application requires. ## Levels of Assurance DigiD supports four [Levels of Assurance (LoA)](/docs/dashboard/glossary.mdx#level-of-assurance-loa): - **Basic** (*Basis*): Username and password. - **Middle** (*Midden*): Username, password and an additional SMS with a one-time verification code or the DigiD app. - **Substantial** (*Substantieel*): The end-user can enable Substantial LoA by performing a one-time check of their identity document in the DigiD app. - **High** (*Hoog*): When authenticating, the end-user scans their identity document with an NFC reader in a phone or device. Applies to identity cards issued after the 13th of March 2021. Although the end-user may choose the LoA during an authentication session, you can require a certain LoA. However, note that you, as a service provider, must set the *minimum* LoA, depending on security level, risk and type of data exchanged. :::tip Setting the LoA Note that you have the obligation, by regulation, to set the appropriate LoA for your service. Learn more in the guidelines at [Betrouwbaarheidsniveaus digitale dienstverlening](https://www.forumstandaardisatie.nl/onderwerpen/veilig-internet/betrouwbaarheidsniveaus). ::: An example of DigiD authentication screen shown to end-users when low LoA is available: End-user DigiD app auth screen ## BSN The citizen service number (BSN) is a unique personal number allocated to everyone registered in the Personal Records Database (BRP). The main purpose of the BSN is to help with contacts between different government organisations, and between individuals and the government. ## About the identity provider The DigiD scheme is managed by [Logius](https://www.logius.nl/), the digital government service of the Netherlands Ministry of the Interior and Kingdom Relations (BZK). Logius maintains government-wide ICT solutions and common standards, that simplify the communication between authorities, citizens and businesses. Logius supplies products relating to access, data exchange, standardization and information security. ## Useful links - [Logius website](https://www.logius.nl/) - [DigiD website](https://www.digid.nl/) - DigiD App: [Android](https://play.google.com/store/apps/details?id=nl.rijksoverheid.digid.pub) and [iOS](https://apps.apple.com/us/app/digid/id1208460960?ls=1) --- ## Attributes reference(Digid) You use DigiD to verify the end-user's identity and obtain relevant personal details about them. This page shows the end-user information you can retrieve with each authentication protocol. ## Available attributes ### BSN End-users authenticate with DigiD using their citizen service number (BSN). The BSN is available in the response from the authentication flow. Note that BSN corresponds to the national identity number (NIN) returned by other eIDs. ### Sector code The sector code provides information on the type of personal number: :::CustomTable{columnWidths="25% 75%"} | Sector code | Type of personal number | |:------------|:------------------------| | `S00000001` | Social security number (SSN), for example used by Social Insurance Bank (SVB) for Dutch nationals who emigrated before the BSN was introduced. | | `S00000000` | Burgerservicenummer (BSN). Citizen service number in the Netherlands. | ::: The sector code is returned in the "idpID" field of a response, by default. Example of a combination of sector code with personal number `:`: `s00000000:999999990`. :::tip Check the sector code Note that you should check whether the sector code as returned complies with the expected sector code and handle it appropriately. If an unexpected sector code is returned, the authentication must be cancelled. ::: #### Strip the sector code You can configure your DigiD implementation to remove the sector code from the subject in the response by default. To achieve this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn/). 2. Select **DigiD** to edit the connection configuration. 3. Tick **Strip sector code from nameId** if you do not want to receive the sector code in the response. 4. Click **Save** to save the changes. After you have enabled **Strip sector code from nameId**, all future authentication sessions will return the BSN (or the SSN) value without the sector code in the subject. As a consequence, `idpId` will return the BSN/SSN alone without the sector code, so for example `999999990` instead of `S00000001:999999990`. ## OIDC scopes and claims You can use the following scopes to request user information from an end-user using DigiD: :::CustomTable{columnWidths="20% 20% 20% 40%"} | Scope | OIDC Claim | Example | Description | |:------| :--------- | :----------- |:----------- | | `idp-id` | `idp_id` | `S00000001:999999990` | Personal identifier set by the identity provider containing the sector scope. | | `nin` | `nin` | `999999990` | National identification number (burgerservicenummer; BSN) of the end-user, consisting of 9 digits. | | | `nin_issuing_country` | `NL` | Issuing country of the national identity. | | | `nin_type` | `BSN` or `SSN` | Type of sector code. If sector code is `s00000000`, then `nin.type` is `BSN`. If `s00000001`, then `SSN`. | ::: ### OIDC responses To trigger an end-user authentication flow with OIDC, the URL could look like: ```sh https:///auth/open/connect/authorize? client_id= &response_type=code &redirect_uri= &scope=openid%20nin%20idp-id &acr_values=idp:digid &prompt=login ``` After an end-user completes the authentication flow with DigiD, you receive a server response with an access token and an ID token in the body of the response. An ID token is a JWT that looks like: `eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA` :::details What is a JWT? A JSON Web Token (JWT) consists of three parts separated by dots (`.`), which correspond to: - Header - Payload - Signature A JWT typically looks like: `xxxxx.yyyyy.zzzzz` ::: The decoded payload (data) part of the ID token for DigiD would then look like: ```json { "iss": "https:///auth/open", "nbf": 1709652445, "iat": 1709652445, "exp": 1709653045, "aud": "", "amr": [ "external" ], "at_hash": "r99QeeZDCO4XHixurU_HTA", "sid": "5866A06...D1433A9649", "sub": "M8DuuHPYvP...Z0vsnZivrfFjs=", "auth_time": 1709652442, "idp": "digid", "idp_id": "s00000000:999999990", "nin": "999999990", "nin_type": "BSN", "nin_issuing_country": "NL", "idp_issuer": "https:///saml/idp/metadata", "transaction_id": "94b2b88c-d2f7-5942-ff4f1cb966f8" } ``` :::tip ID Token with `nin` Note that ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes). With DigiD, `nin` is not present in the ID token by default. To control the data returned in the ID Token, edit the **ID Token User data** in the **Advanced > Security** tab of your OIDC client configuration. Alternatively, you may retrieve the `nin` from the UserInfo endpoint. ::: ### OIDC response example The response examples below show user information that could be contained in the ID Token or retrieved from the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. #### Example with all scopes and sector code Scope: `openid idp-id nin`. ```json { "idp_id":"s00000000:999999990", "nin":"999999990", "nin_type":"BSN", "nin_issuing_country":"NL", "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example with all scopes without sector code Scope: `openid idp-id nin`. ```json { "idp_id": "999999990", "nin": "999999990", "nin_type": "BSN", "nin_issuing_country": "NL", "sub":"ISXRTsmO...F2ZhMWdi9aPc=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example with sector code and without NIN Scope: `openid idp-id`. ```json { "idp_id":"s00000000:999999990", "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example with sector code and without IdP ID Scope: `openid`, `nin`. ```json { "nin":"999999990", "nin_type":"BSN", "nin_issuing_country":"NL", "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example without additional scopes Scope: `openid`. ```json { "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` ## Authentication REST API attributes The Signicat Authentication REST API supports the following request attributes for DigiD: :::CustomTable{columnWidths="20% 20% 20% 40%"} | Attributes | Sub-field | Example | Description | | :------------ | :--------- | :--------- | :---------------- | | `idpId` | | `s00000000:999999990` | Personal identifier set by the identity provider. | | `nin` | `value` | `999999990` | National identification number (BSN) of the end-user. | | | `issuingCountry` | `NL` | Issuing country of the national identity. | | | `type` | `BSN` or `SSN` | Type of sector code. If sector code is `s00000000`, then `nin.type` is `BSN`. If `s00000001`, then `SSN`. | ::: ### Authentication API response example Here is a section of the response showing the user information attributes: ```json ... "subject": { "id": "999999990", "idpId": "s00000000:999999990", "nin": { "value": "999999990", "issuingCountry": "NL", "type": "BSN" }, } ... ``` ## SAML 2.0 attributes Integrating with SAML 2.0, allows you to use the following request attributes for DigiD: :::CustomTable{columnWidths="33% 33% 33%"} | Attributes | Example | Description | | :---------- | :--------- | :------------- | | `idpId` | `s00000000:999999990` | Personal identifier set by the identity provider. | | `nin` | `999999990` | National identification number (BSN) of the end-user. | | `nin.issuingCountry` | `NL` | Country issuing the national identity. | | `nin.type` | `BSN` or `SSN` | Type of sector code. If sector code is `s00000000`, then `nin.type` is `BSN`. If `s00000001`, then `SSN`. | ::: ### SAML 2.0 response example ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... HASHED_SUBJECT ENTITY_ID 999999990 NL BSN urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport https://was-preprod1.digid.nl/saml/idp/metadata ``` --- ## DigiD DigiD is an electronic identification method in the Netherlands that allows citizens with a burgerservicenummer (BSN) to access the online services of organisations with a public function. If you want to read more high-level documentation about DigiD before you start the integration, see [About DigiD](/identity-methods/digid/about-digid.mdx). :::note DigiD facts - Countries: Netherlands - Use cases: Authentication, authentication-based electronic signing - Supported protocols: OIDC, Authentication REST API, SAML 2.0 - Devices: Mobile, desktop - Key attributes: National identity number (BSN) - LoA: Basic, Low, Medium, High ::: ## Get started * [**Integration guide**](/identity-methods/digid/integration/): Follow step-by-step guides to connect to DigiD * [**Attributes reference**](/identity-methods/digid/attribute-reference): Attributes and response examples per protocol ## Learn more * [**About DigiD**](/identity-methods/digid/about-digid): High-level description of how DigiD works * [**Use cases**](/identity-methods/digid/use-cases): Read about the usage context of DigiD ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Order certificates :::warning Important To set up DigiD, you first need to complete the [Initial preparations](/identity-methods/digid/integration/prerequisites.mdx). Without following those important steps you may experience delays, technical difficulties or even unnecessary expenses. ::: ## 1. Create a CSR in the Dashboard A **Certificate Signing Request (CSR)** contains identifying information about your organisation. When applying for a PKIo certificate, you need to create a CSR and share it with a Certificate Authority (CA). Doing this allows the CA to verify your business and issue a PKIo certificate. To create a CSR in the Signicat Dashboard, follow these steps: 1. Go to the **Signicat Dashboard** > [**Organisation management**](https://dashboard.signicat.com/org-mgmt/). 2. Select the account to create a CSR for. 3. In the account management page, select [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 4. In **Certificate Signing Requests**, select **Create**. 5. Fill in the fields in the form: :::CustomTable{columnWidths="25% 20% 30% 25%"} | Information | Distinguished Names | Description | Example | |:------|:------------|:------------|:------------| | Common name | `CN` | The [fully qualified domain name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to secure for your integration. | some.example.com | | Serial number | `SERIALNUMBER` | The [Organisation Identification Number (OIN)](https://www.logius.nl/domeinen/toegang/organisatie-identificatienummer) assigned by Logius to your organisation. This field is compulsory for eHerkenning certificates. | 0000000X123456780000 | | Organisation name | `O` | Registered legal name of your organisation. | Signicat AS | | Organisation unit | `OU` | Internal organisation department/division name | IT | | Country | `C` | The [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) where your organisation is registered. | NL | | Locality | `L` | Town, city, village name. | Amsterdam | | State or Province | `ST` | Province, region, county or state. | Noord-Holland | | Subject Alternative Names | `SAN` | Optional. Provide a FQDN like the Common Name (CN) field or leave empty. | some.example.com | ::: 6. Select **Create** to generate the Certificate Signing Request (CSR) based on the information you submitted. 7. Select **Download** to download the newly created CSR. A CSR is represented as a Base64 encoded string: ```bash -----BEGIN CERTIFICATE REQUEST----- ...Base64-encoded string... -----END CERTIFICATE REQUEST----- ``` Remember that you need to share the CSR with the Certificate Authority (CA) when you apply for a PKIo certificate, as explained in the next step below. ## 2. Purchase PKIo certificates :::tip What are PKIo certificates? PKIo certificates are Public Key Infrastructure (PKI) certificates used to cryptographically sign messages between Signicat and the network infrastructure of Logius. Learn more about PKIo certificates at [https://cert.pkioverheid.nl/](https://cert.pkioverheid.nl/) and [https://www.logius.nl/english/pkioverheid](https://www.logius.nl/english/pkioverheid). ::: PKIo certificates are required to connect to DigiD, DigiD CombiConnect or eHerkenning. To integrate successfully, you need to purchase and configure two separate certificates: 1. One PKIo certificate for sandbox (preproduction) 2. One PKIo certificate for production :::note Lead time Note that obtaining a new PKIo certificate may take up to *five* working days. ::: #### Supported PKIo certificate types The PKIo certificates must be of one of these types: - **Staat der Nederlanden - G4 Root Priv G-Other - 2024** (until 2039) - G4 Intm Priv G-Other LP - 2024 (recommended) - **Staat der Nederlanden Private Root CA - G1** (until 2028) - Staat der Nederlanden Private Services CA - G1 - **Staat der Nederlanden Root CA - G3** (until 2028) - Staat der Nederlanden Organization Services CA - 2023 - Staat der Nederlanden Organisatie Services CA - G3 #### Certificate providers You can purchase PKIo certificates from any of the Trust Service Providers (TSPs) approved by Logius. For a list of authorised providers, see the [PKIoverheidcertificaat aanvragen](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/pkioverheidcertificaat-aanvragen) page. :::warning Additional requirements for Digidentity certificates To purchase Digidentity certificates, Signicat must first generate the appropriate Certificate Signing Request (CSR) for you. Please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::info Purchase checklist When purchasing PKIo certificates, make sure that: 1. You only use the **Certificate Signing Request (CSR)** obtained in the Signicat Dashboard. If you purchase the certificates independently or without the CSR, your integration will fail. 2. You purchase two separate **PKIoverheid (PKIo)** certificates: one for the sandbox environment and one for the production environment. 3. The type of PKIo certificate is one of the [Supported PKIo certificate types](#supported-pkio-certificate-types). When purchasing a certificate, you should explicitly ask the provider to use the CSR you generated in the Signicat Dashboard. ::: You can find more instructions to guide you with purchasing PKIo certificates from a trusted provider on the Logius website at [PKIoverheid-certificaat aanvragen](https://www.logius.nl/domeinen/toegang/pkioverheidcertificaat-aanvragen). :::info New regulations The importance of certificates is increasing and regulations around certificates are changing. Learn more about the [new generation of PKIo certificates](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/wees-voorbereid-de-nieuwe-generatie-pkioverheidcertificaten-komen-eraan). ::: ## 3. Upload PKIo certificates in the Dashboard Once you have purchased and received the PKIo certificates from a certificate provider, you need to upload the *public* part of the certificates (`.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a PKIo certificate to the Signicat Dashboard, do the following: 1. Navigate to **Account management** > [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** to upload the PKIo certificate from your device. Alternatively, you can send us the new PKIo certificate either by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or by contacting your onboarding manager. :::note Certificate activation time Please allow up to 4 hours for the certificates to become active and ready for use. If you require expedited processing, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request priority handling. ::: :::tip Where to find PKIo certificates in the Signicat Dashboard When you upload a PKIo certificate, you store the (public) PKIo certificate in the Signicat Dashboard infrastructure. To view your certificates, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**eID Hub**](https://dashboard.signicat.com/auth). 2. In the left-side menu, navigate to **Advanced** > **Certificates**. 3. Here, you can review your active certificates and access more details, such as issuer and validity window. ::: :::tip Renewing expiring certificates When your PKIo certificate is about to expire, you need to renew your certificate and communicate the changes to Logius. Learn how to renew your certificates in the [How to renew PKIo certificates](/identity-methods/digid/integration/renew-certificates.mdx) guide. ::: ## Next step To continue your integration, proceed to the guide below: * [**3. Setup a DigiD in pre-production**](/identity-methods/digid/integration/setup): Choose a protocol and configure DigiD in pre-production --- ## Integration guide(Integration) To establish a connection with DigiD through Signicat, you need to meet a few requirements like complying with Logius standards and integrating with Signicat in the Dashboard. Note that DigiD may only be used by service providers operating in the public domain. The guides below provide all the steps to help you bring your DigiD connection to production. ## Guides * [**1. Initial preparations**](/identity-methods/digid/integration/prerequisites): Sign agreements with Signicat and Logius * [**2. Order certificates**](/identity-methods/digid/integration/certificates): Create a CSR and purchase PKIoverheid certificates * [**3. Setup a DigiD in pre-production**](/identity-methods/digid/integration/setup): Choose a protocol and configure DigiD in pre-production * [**4. Go to production**](/identity-methods/digid/integration/production): Connect to the DigiD production account --- ## Initial preparations Before you can start integrating with Signicat's implementation for DigiD, you must complete a series of steps that include signing agreements and obtaining certificates. This page contains information about the onboarding steps you need to take before you can start testing and using DigiD. Note that the DigiD application process requires communication between your organisation and Logius, the provider of DigiD, and also between your organisation and the Signicat onboarding team. :::warning Pre-production and production It is important to note that you must first integrate in a pre-production/test environment. You can integrate with DigiD in a production environment only after you have received approval on your pre-production setup. ::: :::note Checklist for DigiD ::: ## 1. Sign agreements with Signicat The first step to connect to DigiD involves signing contractual agreements with Signicat. These are necessary to grant you access to our services. In particular, you need to sign: 1. An agreement contract 2. A data processing agreement (DPA) (signed by a legal representative) If you want to integrate with DigiD, contact us to get started with these agreements: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) :::warning Type of organisation Note that integration with DigiD is restricted to organisations offering services in the public domain such as the government, educational institutes, healthcare institutions or pension funds. ::: ## 2. Comply with Logius requirements Before you can connect to DigiD, your organisation must comply with the mandatory look, security and infrastructure requirements of Logius. Your connection needs to meet the criteria specified in: - [DigiD ICT security guidelines for web applications](https://www.logius.nl/domeinen/toegang/digid/ict-beveiligingsassessments-digid) - [Checklist aansluiten](https://logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen) Your DigiD connection must undergo an official assessment by an external and certified DigiD auditor within two months after going to production. Your organisation should arrange the audit as part of the integration process. Note that organisations connected to DigiD undergo an annual ICT security assessment. You can find more information in the [official connection procedure for DigiD](https://www.logius.nl/domeinen/toegang/digid/aansluiten-wijzigen). :::note About Signicat and DigiD The Signicat integration of DigiD specs undergoes a separate yearly assessment for which we supply our DigiD Generieke Rapporten voor de Serviceorganisatie (RSO, formerly TPM) certificate to our service providers. You use the Signicat RSO certificate in your audit with Logius. ::: :::warning About theming and DigiD Logius requires that no Signicat logo appears on pages shown to your end-user. This means that, before your audit with Logius, you should create a custom theme for your account. Follow the steps described in the [Theming](/docs/dashboard/branding/theming.mdx) documentation to create and apply a theme without the Signicat logo. ::: ## 3. Register with RvIG Registration with the Dutch governmental organisation Rijksdienst voor Identiteitsgegevens (RvIG) is needed when organisations intend to use a person's BSN attribute. As part of the assessment, RvIG checks whether your organisation can be authorised to request a person's BSN during authentication. You can find the application form for BSN eligibility in the [Aanvraagformulier Toetsing BSN-gerechtigdheid](https://www.rvig.nl/aanvraagformulier-bsn-gerechtigdheid). ## 4. Configure your Signicat account :::tip New customers If you are new to Signicat, sign up for a free Signicat account by completing the following initial preparations: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. For more details, see the [Get started with Signicat](/docs/) guide. 2. In the Dashboard, make sure you have set up an [organisation](/docs/dashboard/organisation-management/organisations.mdx). ::: When integrating with DigiD, you must first test and get approval for the pre-production account before you can proceed with the integration in a production account. Logius offers two separate environments for your integration with DigiD: - Pre-production (test environment) - Production Signicat matches this design with two separate types of accounts: - Sandbox account - Production account The subsection below guides you through your account configuration in the Signicat Dashboard. ### Create a sandbox account with a custom domain To test DigiD in the pre-production environment, you need to create a sandbox account with a custom domain in the Signicat Dashboard. To do this, go to the [Signicat Dashboard](https://dashboard.signicat.com/) and: 1. Create a sandbox account. For detailed instructions, see the [Create an account](/docs/dashboard/organisation-management/accounts.mdx#create-an-account) section. :::tip Existing customers If you are an existing Signicat customer, you may reuse a sandbox account that you have previously created. ::: 2. Add a [custom domain](/docs/dashboard/organisation-management/domains/custom/) to the sandbox account. :::warning Custom domain Note that you must add a *custom* domain. Accounts with a Signicat subdomain (for example, `mycompany.signicat.com`) cannot be used to connect to DigiD. ::: :::tip Using Let's Encrypt certificates If you wish to use [Let's Encrypt](https://letsencrypt.org/) certificates as TLS server certificates for DigiD, you must use a `.nl` domain. Learn more in the [Logius documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie/factsheet-dv-en-ov-certificaten-bij-digid). ::: Once you have created a sandbox account with a custom domain, you can proceed to create a Certificate Signing Request (CSR). This is needed to obtain PKIo certificates for DigiD. ## Next step * [**2. Order certificates**](/identity-methods/digid/integration/certificates): Create a CSR and purchase PKIoverheid certificaes --- ## Go to production :::warning Important To set up DigiD in production, you first need to get your pre-production integration approved by Logius. Make sure you have completed the steps described in the [Setup up DigiD pre-production](/identity-methods/digid/integration/setup.mdx) page. ::: ## Prerequisites To go to production, you must first meet these prerequisites: - [Purchase a PKIoverheid certificate](/identity-methods/digid/integration/certificates.mdx) for production - Get your [pre-production setup](/identity-methods/digid/integration/setup.mdx) approved by Logius ## 1. Create a production account To connect to DigiD in production, you need to set up a production account with a custom domain in the Signicat Dashboard. You can always reuse a production account that you created previously. To create a new production account, do the following: 1. Go to **Signicat Dashboard** > [Organisation management](https://dashboard.signicat.com/org-mgmt/). 2. Select **Add Account**. 3. Enter the name of your account under **Account Name** and tick the box for **Production account**. Note that this requires that already completed your company's onboarding in the Dashboard. 4. Select **Create** to create the new account. In the next screen, select **Add new domain** to add a custom domain. ### Add a custom domain To add a custom domain, follow the instructions for [Custom domains](/docs/dashboard/organisation-management/domains/custom/). Then, return to this page to continue with the integration. :::warning Custom domain Note that you must add a *custom* domain. Accounts with a Signicat subdomain (for example, `mycompany.app.signicat.com`) cannot be used to connect to DigiD. ::: :::tip Using Let's Encrypt certificates If you wish to use [Let's Encrypt](https://letsencrypt.org/) certificates as TLS/SSL server certificates for DigiD, you must use a `.nl` domain. Learn more in the [Logius documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie/factsheet-dv-en-ov-certificaten-bij-digid). ::: ## 2. Upload PKIo certificates :::warning Order certificates This step assumes that you have already purchased a PKIoverheid certificate for production. Learn how in our documentation to [Order certificates](/identity-methods/digid/integration/certificates.mdx). ::: Now, upload the public part of the PKIo certificates (in `.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a certificate: 1. Go to [**Account management > Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** and select the certificate from your device. Alternatively, you can either: - Send them to us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. - Send them to the onboarding manager. ## 3. Add DigiD in the Dashboard You can now add DigiD to your eIDs. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. ### eID configuration You can edit the settings of your DigiD connection: :::details Click to expand DigiD Dashboard settings - **Strip sector code from nameID**: Logius sends a prefix with the citizen service number (BSN). Some service providers can't handle that. Tick this checkbox to strip away the sector code/prefix. **Advanced configuration** To configure advanced settings, go to the "Advanced" tab in the DigiD page and specify: - **Select attribute filter:** Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). - **Include only when scoped:** If ticked, the eID will _not_ be visible by default on the eID selection screen, unless you specify it by using [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx). - **Response attribute mappings:** You can customise the name of the attributes received in the response body. Provide none or multiple name-to-name mappings. - **Use web flow on mobile device:** If you are configuring the WEB flow for your connection, you may still want to use it from mobile devices. If you are using the DigiD app, the redirect (in some situations) opens in the mobile device's native browser. In such cases, we need to perform an operation called "session restoration" which may incur in security issues. We have taken a number of mitigations on our side to reduce the risks of such threats. However, some risks cannot be addressed on our side. If you want to use this option, you have to accept such risks. For further information, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. :::tip Mitigating risks To fully mitigate the residual risk, we recommend you implement the following on your side: You should only accept a response back from Signicat if you are able to match that response to a request that you have sent earlier. You can achieve this, for instance, by storing the request you have sent in the user session. ::: Adjust the settings as necessary and click **Save** to apply the changes. ## 4. Get Signicat metadata To apply for a DigiD connection with Logius, you need the Signicat SAML metadata (in XML format). To download the metadata file: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **DigiD** from the list of active eIDs. 3. Select **Get Signicat metadata** to download the XML file to your device. Save the downloaded metadata file locally. You will upload this file to Logius in the next step. ## 5. Request DigiD in production To connect to DigiD production environment, you need to fill in the Logius [Aanvraagformulier](https://www.logius.nl/domeinen/toegang/digid/aanvraagformulier-digid) (*Application form*). :::details How to fill in the Logius Aanvraagformulier When filling in the Logius [Aanvraagformulier](https://www.logius.nl/domeinen/toegang/digid/aanvraagformulier-digid) (*Application form*), consider the following key fields: | Field | Recommended input or selection | |---|---| | Mijn organisatie is een*(My organisation is a)* | Select the type of your organisation: **Overheidsorganisatie/overig** (Government organisation/other) or **Leverancier** (third-party supplier). | | Wilt u voor deze aansluiting een sub-OIN gebruiken?*(Do you want to use a sub-OIN?)* | Select **Nee** (No) to use your main Organisation Identification Number (OIN). Select **Ja** (Yes) only if you register a specific sub-OIN for this connection. | | Op welke omgeving wilt u aansluiten?*(Which environment do you want to connect to?)* | Select **Productieomgeving** (Production environment). Note that your pre-production environment must have already been tested and approved by Logius before you can apply for the production environment. Learn more in the [Set up DigiD pre-production](/identity-methods/digid/integration/setup/#5-get-your-pre-production-setup-approved) guide. | | URL aansluiting productieomgeving*(URL production connection)* | Enter your application's production endpoint URL where your end-users can start the authentication with DigiD. This must be a webpage on your own website that you set up yourself; do not enter the Signicat eID and Wallet Hub URL in this field. The page should contain a DigiD button linking to the authentication URL. The URL must begin with `https://`. | | Dienstnaam*(Service name)* | Enter only the name of your service (for example, "Client Portal"). Logius combines this with your organisation name to show your users "Your Organisation - Client Portal". | | Metadata in xml-formaat*(Metadata in XML format)* | Upload the Signicat SAML metadata XML file that you downloaded in the [4. Get Signicat metadata](#4-get-signicat-metadata) step. | ::: ## 6. Set up a connection with a protocol To establish a connection between Signicat DigiD and your application, you need to use an authentication protocol. ### Choose a protocol :::tip Supported authentication protocols Signicat supports the standard **OpenID Connect (OIDC)** and **SAML 2.0** protocols. In addition, we offer our bespoke **Signicat Authentication REST API**. The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API. To learn more about these authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: ### Set up the protocol For information on how to set up the different protocols, see the [eID and Wallet Hub - Quick start guide](/docs/eid-hub/quick-start/). ### Data and attributes To learn more about attributes, scopes and claims supported by each authentication protocol, visit the [Attributes reference](/identity-methods/digid/attribute-reference.mdx) page. ## 7. Activate your connection Submit a request for activation of your connection to the DigiD production environment in the [DigiD Wijzigingsformulier](https://www.logius.nl/domeinen/toegang/digid/wijzigingsformulier-digid). In the form, select "Ik wil mijn productieaansluiting activeren". ## 8. Ask Logius to approve your connection After you set up the connection in production, you need to test it and submit a request for approval by Logius. - Test your implementation using the [Checklist for connecting to DigiD](https://www.logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen). - Apply changes to meet the requirements. - Ask Logius to verify your integration by requesting a connection test with the form [Aanvragen test DigiD-aansluiting](https://www.logius.nl/domeinen/toegang/digid/aanvragen-test-digid-aansluiting). ## 9. Audit and assessment Your DigiD integration in production should adhere to security standards to ensure secure end-user authentication. Logius performs audits and checks to ensure your infrastructure and connection comply with such requirements. Your DigiD integration must undergo an official assessment by an external and certified DigiD auditor within two months after going to production. Additionally, organisations that use DigiD must conduct an annual IT security assessment. Arrange the audits according to the specifications in the DigiD [ICT-beveiligingsassessments](https://www.logius.nl/domeinen/toegang/digid/ict-beveiligingsassessments-digid) guide. :::note Signicat RSO certificate Signicat, as a third-party provisioning service for DigiD, undergoes a Rapporten voor de Serviceorganisatie (RSO, formerly TPM) yearly assessment. For this, we need to plan the RSO audit as early as possible in the year. We can also provide you with our DigiD RSO certificate to use in your audit. Note that the yearly required assessment planning for municipalities in NL and for DigiD occurs at different times of the year and might lead to some delays. Therefore, we recommend you plan sufficient time around the assessment with municipalities' own audits. ::: ## 10. Renewing certificates When your PKIo certificate is about to expire, you need to renew your certificate and communicate the changes to Logius. Learn how to renew your certificates in the [How to renew PKIo certificates](/identity-methods/digid/integration/renew-certificates.mdx) guide. ## Useful links - [Logius - Aansluiten op DigiD](https://www.logius.nl/domeinen/toegang/digid/aansluiten-wijzigen) - [Logius - DigiD](https://www.logius.nl/domeinen/toegang/digid) - [DigiD documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie) --- ## How to renew PKIo certificates PKIo certificates have a set expiry date and must be renewed periodically for security purposes. Renewing an expiring certificate requires to update your configuration in the Signicat Dashboard and communicate the change with Logius. This page outlines the steps to follow when you need to renew an expiring PKIo certificate. ## 1. Create a CSR in the Dashboard A **Certificate Signing Request (CSR)** contains identifying information about your organisation. When applying for a PKIo certificate, you need to create a CSR and share it with a Certificate Authority (CA). Doing this allows the CA to verify your business and issue a PKIo certificate. To create a CSR in the Signicat Dashboard, follow these steps: 1. Go to the **Signicat Dashboard** > [**Organisation management**](https://dashboard.signicat.com/org-mgmt/). 2. Select the account to create a CSR for. 3. In the account management page, select [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 4. In **Certificate Signing Requests**, select **Create**. 5. Fill in the fields in the form: :::CustomTable{columnWidths="25% 20% 30% 25%"} | Information | Distinguished Names | Description | Example | |:------|:------------|:------------|:------------| | Common name | `CN` | The [fully qualified domain name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to secure for your integration. | some.example.com | | Serial number | `SERIALNUMBER` | The [Organisation Identification Number (OIN)](https://www.logius.nl/domeinen/toegang/organisatie-identificatienummer) assigned by Logius to your organisation. This field is compulsory for eHerkenning certificates. | 0000000X123456780000 | | Organisation name | `O` | Registered legal name of your organisation. | Signicat AS | | Organisation unit | `OU` | Internal organisation department/division name | IT | | Country | `C` | The [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) where your organisation is registered. | NL | | Locality | `L` | Town, city, village name. | Amsterdam | | State or Province | `ST` | Province, region, county or state. | Noord-Holland | | Subject Alternative Names | `SAN` | Optional. Provide a FQDN like the Common Name (CN) field or leave empty. | some.example.com | ::: 6. Select **Create** to generate the Certificate Signing Request (CSR) based on the information you submitted. 7. Select **Download** to download the newly created CSR. A CSR is represented as a Base64 encoded string: ```bash -----BEGIN CERTIFICATE REQUEST----- ...Base64-encoded string... -----END CERTIFICATE REQUEST----- ``` Remember that you need to share the CSR with the Certificate Authority (CA) when you apply for a PKIo certificate, as explained in the next step below. ## 2. Purchase a new PKIo certificate :::tip What are PKIo certificates? PKIo certificates are Public Key Infrastructure (PKI) certificates used to cryptographically sign messages between Signicat and the network infrastructure of Logius. Learn more about PKIo certificates at [https://cert.pkioverheid.nl/](https://cert.pkioverheid.nl/) and [https://www.logius.nl/english/pkioverheid](https://www.logius.nl/english/pkioverheid). ::: PKIo certificates are required to connect to DigiD, DigiD CombiConnect or eHerkenning. To integrate successfully, you need to purchase and configure two separate certificates: 1. One PKIo certificate for sandbox (preproduction) 2. One PKIo certificate for production :::note Lead time Note that obtaining a new PKIo certificate may take up to *five* working days. ::: #### Supported PKIo certificate types The PKIo certificates must be of one of these types: - **Staat der Nederlanden - G4 Root Priv G-Other - 2024** (until 2039) - G4 Intm Priv G-Other LP - 2024 (recommended) - **Staat der Nederlanden Private Root CA - G1** (until 2028) - Staat der Nederlanden Private Services CA - G1 - **Staat der Nederlanden Root CA - G3** (until 2028) - Staat der Nederlanden Organization Services CA - 2023 - Staat der Nederlanden Organisatie Services CA - G3 #### Certificate providers You can purchase PKIo certificates from any of the Trust Service Providers (TSPs) approved by Logius. For a list of authorised providers, see the [PKIoverheidcertificaat aanvragen](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/pkioverheidcertificaat-aanvragen) page. :::warning Additional requirements for Digidentity certificates To purchase Digidentity certificates, Signicat must first generate the appropriate Certificate Signing Request (CSR) for you. Please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::info Purchase checklist When purchasing PKIo certificates, make sure that: 1. You only use the **Certificate Signing Request (CSR)** obtained in the Signicat Dashboard. If you purchase the certificates independently or without the CSR, your integration will fail. 2. You purchase two separate **PKIoverheid (PKIo)** certificates: one for the sandbox environment and one for the production environment. 3. The type of PKIo certificate is one of the [Supported PKIo certificate types](#supported-pkio-certificate-types). When purchasing a certificate, you should explicitly ask the provider to use the CSR you generated in the Signicat Dashboard. ::: You can find more instructions to guide you with purchasing PKIo certificates from a trusted provider on the Logius website at [PKIoverheid-certificaat aanvragen](https://www.logius.nl/domeinen/toegang/pkioverheidcertificaat-aanvragen). :::info New regulations The importance of certificates is increasing and regulations around certificates are changing. Learn more about the [new generation of PKIo certificates](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/wees-voorbereid-de-nieuwe-generatie-pkioverheidcertificaten-komen-eraan). ::: ## 3. Upload PKIo certificates in the Dashboard Once you have purchased and received the PKIo certificates from a certificate provider, you need to upload the *public* part of the certificates (`.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a PKIo certificate to the Signicat Dashboard, do the following: 1. Navigate to **Account management** > [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** to upload the PKIo certificate from your device. Alternatively, you can send us the new PKIo certificate either by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or by contacting your onboarding manager. :::note Certificate activation time Please allow up to 4 hours for the certificates to become active and ready for use. If you require expedited processing, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request priority handling. ::: :::tip Where to find PKIo certificates in the Signicat Dashboard When you upload a PKIo certificate, you store the (public) PKIo certificate in the Signicat Dashboard infrastructure. To view your certificates, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**eID Hub**](https://dashboard.signicat.com/auth). 2. In the left-side menu, navigate to **Advanced** > **Certificates**. 3. Here, you can review your active certificates and access more details, such as issuer and validity window. ::: ## 4. Get Signicat metadata To switch your connection from an expiring PKIo certificate to a new PKIo certificate, you need to share the metadata of the new PKIo certificate with Logius. To do this, you need to complete these steps: 1. Download a metadata containing the details of the new PKIo certificate. 2. Submit a change request to Logius to update your connection configuration with the metadata of the new certificate. The instructions below explain how to achieve this. :::warning Important - Downtime expected It is important to note that downtime is to be expected, while switching DigiD connections from one certificate to another. This is due to Logius infrastructure design which supports one certificate at a time. Note that authentication transactions will fail while you are waiting for Logius to update your connection with your new certificate metadata. It is recommended that you inform your end-users promptly. To avoid downtime while retrieving the metadata for your new PKIo certificate, advanced users can follow the [Advanced flow to reduce downtime](#advanced-flow-to-reduce-downtime) steps below. ::: To get the Signicat metadata for your PKIo certificate, do the following 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. In the left menu, navigate to **Advanced** > [**Certificates**](https://dashboard.signicat.com/bca/certificates/edit). Here you can view your active certificates. The active (in use) certificate is marked by the radio button. 3. Select the new PKIo certificate you intend to switch to and set it to active. :::warning Important While the new PKIo certificate is set to active, transactions with your existing DigiD connection will fail until you reset the old (expiring) certificate to active, as explained in step 7 below. To avoid downtime while retrieving the metadata for your new PKIo certificate, advanced users can follow the [Advanced flow to reduce downtime](#advanced-flow-to-reduce-downtime) below. ::: 4. In the left menu, navigate to [**eIDs**](https://dashboard.signicat.com/bca/authn) and choose **DigiD** from the list. 5. In the DigiD configuration, click **Get Signicat metadata**. This opens your metadata, which includes your new PKIo certificate, in a new tab in your browser. 6. Save the metadata as an XML file. You can do this by right-clicking in the page and selecting "Save as...". Then, save the XML file on your local device. 7. **Important**: In the left menu, go back to **Advanced** > [**Certificates**](https://dashboard.signicat.com/bca/certificates/edit) and switch back to your expiring certificate. This is to avoid downtime while Logius approves your new metadata request. :::note Reminder Remember to switch back to the expiring certificate as explained in step 7 above. After you switch back to the expiring certificate, your end-users can successfully complete authentication transactions. ::: ##### Advanced flow to reduce downtime You can avoid downtime while retrieving the metadata for your new PKIo certificate by following the advanced guide below. Note that this will only mitigate downtime to obtain the new metadata. You should still expect downtime while you wait for Logius to update your connection, as explained in [5. Submit change to Logius](#5-submit-change-to-logius). ::::details Advanced flow - How to reduce downtime 1. Obtain the following properties from your new PKIo certificate: - **SHA 256 fingerprint**: - `openssl x509 -noout -fingerprint -sha256 -inform pem -in | sed 's/SHA256 Fingerprint=//g' | tr -d ':' | tr '[:upper:]' '[:lower:]'` - **Base64 encoded certificate string**: - `sed '/---/d' _.qwant.com.pem | tr -d '\n\r'; echo` :::warning Format guidelines Make sure you remove enclosures (`-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`) and any new line character from the certificate string. ::: 2. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 3. In the left menu, navigate to [**eIDs**](https://dashboard.signicat.com/bca/authn) and choose **DigiD** from the list. 4. In the DigiD configuration, click **Get Signicat metadata**. This opens your existing connection metadata, including your expiring PKIo certificate details, in a new tab in your browser. 5. Save the metadata as an XML file. You can do this by right-clicking in the page and selecting "Save as...". Then, save the XML file on your local device. 6. Now, open the XML file with a compatible text editor. 7. Edit the values of the following XML fields: - `SPSSODescriptor` > `KeyDescriptor` > `KeyInfo` > `KeyName`: Substitute the value with the **SHA 256 fingerprint** of you new PKIo certificate that you obtained in step 1. - `SPSSODescriptor` > `KeyDescriptor` > `KeyInfo` > `X509Data` > `X509Certificate`: Substitute the value with the **Base64 encoded certificate string** of you new PKIo certificate that you obtained in step 1. 8. Save the metadata file with the new PKIo certificate values. You need to submit this XML file to Logius, as explained below. :::: ## 5. Submit change to Logius To update your DigiD connection with the new PKIo certificate, you need to submit a change request with the metadata file containing your new PKIo certificate details. To do this, you need to fill in a form on the Logius website. :::info Processing time Note that it may take a few days for Logius to process the change. You can request the change to occur at a specific time window during office hours. ::: To submit the change request to Logius, do the following: 1. Go to [https://www.logius.nl/domeinen/toegang/digid/wijzigingsformulier-digid](https://www.logius.nl/domeinen/toegang/digid/wijzigingsformulier-digid). 2. Fill in the change form (wijzigingsformulier) with the details of your request and upload the metadata for the new PKIo certificate. For example, fill in: - **Op welk koppelvlak bent u aangesloten?**: SAML - **Wat is uw wijziging?**: `Ik wil de metadata vervangen (bijvoorbeeld bij certificaatwissel)` - Enter the following depending on your scenario: - Environment type (omgeving) - Date (datum) - Time (tijd) - Metadata: Provide the XML file with your metadata. 3. Submit the form to Logius and prepare for switching to the new certificate. You can view an example below: DigiD change form (wijzigingsformulier) ## 6. Switching to the new certificate :::tip How to communicate the change We recommend you communicate the incoming maintenance with your end-users on your website or application. For example, you could display a banner that warns users about potential downtime during the time window you agreed with Logius to update your connection to use the new PKIo certificate. ::: It is important that you time your certificate switch with Logius to reduce any potential downtime. When you receive confirmation from Logius and are ready to switch to using the new PKIo certificate, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. In the left menu, navigate to **Advanced** > [**Certificates**](https://dashboard.signicat.com/bca/certificates/edit). 3. Select the new PKIo certificate you intend to switch to and set it to active. Once activated, your DigiD connection will automatically begin using the new PKIo certificate. Authentication transactions will be using the newly activated PKIo certificate going forward. :::note Renewal complete! ::: --- ## Set up DigiD pre-production :::warning Initial preparations To set up DigiD in pre-production, start with the steps described in the [Initial preparations](/identity-methods/digid/integration/prerequisites.mdx) page. ::: ## 1. Add DigiD in the Dashboard When you want to use an eID, you first need to activate it in the Signicat Dashboard. To do this for DigiD, follow these steps: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. :::note Cannot activate DigiD? If you cannot activate DigiD or require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ### eID configuration DigiD Dashboard settings You can edit the settings of your DigiD connection: - **Strip sector code from nameID**: Logius sends a prefix with the citizen service number (BSN). Some service providers can't handle that. Tick this checkbox to strip away the sector code/prefix. Adjust the settings as necessary and click **Save** to apply the changes. #### Advanced configuration To configure advanced settings, go to the "Advanced" tab in the DigiD page and specify: - **Select attribute filter:** Select an attribute filter to control which attributes you want to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). - **Include only when scoped:** If ticked, DigiD will _not_ be available as an eID for authentication on the eID selection screen, unless you specify it in your authentication request by using [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx) (DigiD scope: `digid`). - **Response attribute mappings:** You can customise the name of the attributes received in the response body. Provide none or multiple name-to-name mappings. - **Use web flow on mobile device:** When you configure DigiD for WEB flows, you may still want to offer authentication through mobile devices. It is important to note that sometimes authentications started in the DigiD app may redirect the user to the native browser of the mobile device. In such cases, we handle the redirect through "session restoration" which may lead to vulnerabilities that require additional security considerations. :::warning Security considerations We have taken a number of measures to reduce the security risks on our side. To ensure secure authentications, you need to take action on the implementation side. If you want to use web flows on mobile devices, you have to be aware of the risks and address them appropriately. For more information, you can read more below or contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::tip Mitigating risks To fully mitigate the residual risk, we recommend you implement the following measures on your side. **Verify the response**: You should accept a response back from Signicat only after you have matched the response to a request that you have sent previously. For example, you can achieve this by storing the request in the user session. ::: ## 2. Get Signicat metadata When you activate DigiD in the Signicat Dashboard, you can download the Signicat SAML metadata (in XML format). You need the Signicat metadata when applying for DigiD with Logius in the next step. To get the metadata file: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **DigiD** from the list of active eIDs. 3. Select **Get Signicat metadata** to download the XML file to your device. Save the downloaded metadata file locally. You will upload this file to Logius in the next step. ## 3. Request DigiD pre-production To connect to DigiD pre-production, you need to fill in the Logius [Aanvraagformulier](https://www.logius.nl/domeinen/toegang/digid/aanvraagformulier-digid) (*Application form*). Learn more about how to do this in the [Filling in the Logius Aanvraagformulier](#filling-in-the-logius-aanvraagformulier) section below. :::info Waiting times According to the Logius [Roadmap](https://www.logius.nl/domeinen/toegang/digid/aansluiten-wijzigen), it takes about five working days to receive the connection details to the DigiD pre-production environment. ::: ### Filling in the Logius Aanvraagformulier When filling in the Logius [Aanvraagformulier](https://www.logius.nl/domeinen/toegang/digid/aanvraagformulier-digid) (*Application form*), consider the following key fields: | Field | Recommended input or selection | |---|---| | Mijn organisatie is een*(My organisation is a)* | Select the type of your organisation: **Overheidsorganisatie/overig** (Government organisation/other) or **Leverancier** (third-party supplier). | | Wilt u voor deze aansluiting een sub-OIN gebruiken?*(Do you want to use a sub-OIN?)* | Select **Nee** (No) to use your main Organisation Identification Number (OIN). Select **Ja** (Yes) only if you register a specific sub-OIN for this connection. | | Op welke omgeving wilt u aansluiten?*(Which environment do you want to connect to?)* | Select **Preproductieomgeving** (Pre-production environment). You must always complete the pre-production setup before you apply for production. | | URL aansluiting preproductieomgeving*(URL pre-production connection)* | Enter your application's pre-production endpoint URL where your end-users can start the authentication with DigiD. This must be a webpage on your own website that you set up yourself; do not enter the Signicat eID and Wallet Hub URL in this field. The page should contain a DigiD button linking to the authentication URL. The URL must begin with `https://`. | | Dienstnaam*(Service name)* | Enter only the name of your service (for example, "Client Portal"). Logius combines this with your organisation name to show your users "Your Organisation - Client Portal". | | Metadata in xml-formaat*(Metadata in XML format)* | Upload the Signicat SAML metadata XML file that you downloaded in the [2. Get Signicat metadata](#2-get-signicat-metadata) step. | ## 4. Set up a connection with a protocol To establish a connection between DigiD and your application, you need to use an authentication protocol. Note that you only need to set up a connection to the Signicat eID and Wallet Hub servers. Signicat handles the connection with DigiD separately, therefore acting as a message broker between your application and DigiD. ### Choose a protocol :::tip Supported authentication protocols Signicat supports the standard **OpenID Connect (OIDC)** and **SAML 2.0** protocols. In addition, we offer our bespoke **Signicat Authentication REST API**. The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API. To learn more about these authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: ### Set up the protocol For information on how to set up the different protocols, see the [eID and Wallet Hub - Quick start guide](/docs/eid-hub/quick-start/). ### Data and attributes To learn more about attributes, scopes and claims supported by each authentication protocol, visit the [Attributes reference](/identity-methods/digid/attribute-reference.mdx) page. {/* ### Control the LoA You must set the minimum LoA you require during authentication based on security level, type of data exchanged and risk. Read the guidelines for configuring the LoA at [Betrouwbaarheidsniveaus digitale dienstverlening](https://www.forumstandaardisatie.nl/onderwerpen/veilig-internet/betrouwbaarheidsniveaus). */} ## 5. Get your pre-production setup approved After you set up the pre-production web/mobile service connection, you need to test it and submit a request for approval by Logius. Here are the steps to follow: 1. Test your implementation using the [Checklist for connecting to DigiD](https://www.logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen). 2. Apply the necessary changes to meet the requirements. 3. Ask Logius to verify your integration by requesting a connection test with the form [Aanvragen test DigiD-aansluiting](https://www.logius.nl/domeinen/toegang/digid/aanvragen-test-digid-aansluiting) (*Request test DigiD connection*) form. :::details Filling in the Logius Aanvragen test DigiD-aansluiting form When you fill in the Logius [Aanvragen test DigiD-aansluiting](https://www.logius.nl/domeinen/toegang/digid/aanvragen-test-digid-aansluiting) (*Request test DigiD connection*) form, consider the following key fields: | Field | Recommended input or selection | |---|---| | Aansluitnummer op de preproductie-omgeving*(Connection number on the pre-production environment)* | Enter the pre-production connection number that Logius sent to your organisation. | | Naam van uw leverancier*(Name of your supplier)* | Enter **Signicat**. Signicat is your identity service provider. | | Om welk koppelvlak gaat het?*(Which interface is this about?)* | Select **SAML**. Signicat connects to DigiD using the SAML 2.0 interface. | | Webdienst URL*(Web service URL)* | Enter your application's pre-production endpoint URL where your end-users start the authentication with DigiD. This must be a webpage on your own website that you set up yourself; do not enter the Signicat eID and Wallet Hub URL in this field. The page should contain a DigiD button linking to the authentication URL. The URL must begin with `https://`. | | Is deze omgeving beschikbaar voor Logius?*(Is this environment available for Logius?)* | Make a selection based on whether your environment is available for Logius to reach. | | Voldoet de omgeving volgens u aan de voorwaarden?*(Does the environment meet the conditions according to you?)* | Select **Ja** (Yes). This confirms that you have tested your environment using the Logius checklist and found no issues. | | Vanaf wanneer kunnen we testen?*(From when can we test?)* | Enter the date and time when Logius can begin testing your pre-production connection. | | Gebruikersnaam testaccount / Wachtwoord testaccount*(Username test account / Password test account)* | Enter the username and password of the pre-production DigiD test account that Logius provided you. This allows Logius to log in during the test. | ::: After Logius approves your pre-production connection, you are ready to integrate with DigiD in production. ## Next step * [**4. Go to production**](/identity-methods/digid/integration/production): Connect to the DigiD production account --- ## Use cases for DigiD DigiD can be used to authenticate your end-users. There are several options available for the integration. ## Authentication The most common scenario where to use DigiD is end-user authentication with the services of the public administration or with organisations providing public services in the Netherlands. DigiD authentication requires the BSN of the end-user. ### Example app2app :::tip Note The flow in this section shows an example of authentication performed on the same (mobile) device. A flow for authentication across multiple devices, such as going from laptop to app, consists of more steps. ::: Imagine a situation where an end-user wants to access a restricted section on your mobile application using DigiD. To log in using DigiD for authentication: 1. The end-user locates the DigiD login button on your application. Clicking the button opens the DigiD app automatically. 2. The end-user enters the PIN code to access the DigiD app. 3. The end-user views the confirmation screen in the DigiD app that shows the icon and name of your application. After clicking "Log in", the DigiD app switches back to your application. 4. Once the authentication process is complete, the end-user gains access to your application. The flow would look like: App2app authentication DigiD ## DigiD Machtigen (Authorisation) DigiD Machtigen is a solution for individuals to authorise someone else to log in on their behalf. :::note Important DigiD Machtigen is only possible through the DigiD CombiConnect integration. To learn more, visit the [DigiD CombiConnect](/identity-methods/digid-combiconnect/) documentation. ::: {/* ## Add-on services DigiD allows you to extend your implementation to use cases beyond end-user authentication. ### Signing with DigiD You can integrate DigiD with Signicat's signing solutions to allow end-users to sign documents digitally with their BSN through DigiD. :::tip Substantial LoA When using DigiD with Signicat's signing solutions, we recommend you require end-users to authenticate with "Substantial" Level of Assurance (LoA). To use the "Substantial" confidence level, end-users must perform a one-time verification of their identity card in the DigiD app. This guarantees that the end-users are who they claim they are during digital signing. ::: ### Lookup personal data Lookup of end-user personal information, like name and address, from the official governmental BRP source is possible but only in consultation due to strict regulations, integration, and connection restrictions. For more information, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### DigiD Machtigen DigiD offers "DigiD Machtigen", a solution for voluntary mandates that adds mandates through legal authority (parental guardianship or legal guardianship). With DigiD Machtigen a person can authorise someone to act on their behalf. It is designed to let people who cannot use DigiD (due to lack of digital experience or illness, such as the elderly and children) authenticate with the services of the Dutch public administration. Learn more about [DigiD Machtigen](https://logius.nl/domeinen/toegang/digid-machtigen). */} --- ## About DigiD CombiConnect DigiD CombiConnect is a technical specification and interface provided by Logius for integrating both DigiD and DigiD Machtigen into your digital services. DigiD CombiConnect allows you, as a service provider, to offer your end-users authentication and identity verification with: - **DigiD**: This is an electronic identification (eID) method that allows access to public services and government websites in the Netherlands. :::info Direct DigiD integration We also support direct integrations with DigiD as a standalone service. Learn more in the [DigiD](/identity-methods/digid/) documentation. ::: - **DigiD Machtigen**: Delegated login on behalf of someone else. For example, a parent for a child or a caregiver for a patient. When you integrate DigiD CombiConnect into your service, the CombiConnect Orchestration system figures out which flow to use and where to route the end-users. ## How it works Dutch citizens and residents with a BSN (Dutch citizen service number) can use DigiD to access online administration services, such as taxes, applying for allowances or benefits, or checking pension information. Citizens with limited access to digital tools can delegate responsibility to others (mandates) through DigiD Machtigen. DigiD is an eIDAS-notified eID method and is available through many European public service providers. For service providers, DigiD returns the BSN number of an individual, thus enabling you to verify the identity of your end-users. Note that the BSN is the *only* personal data of an end-user that DigiD provides. ### DigiD Machtigen (Authorisation) DigiD CombiConnect offers **DigiD Machtigen**, a solution for voluntary mandates that adds mandates through legal authority (parental guardianship or legal guardianship). With DigiD Machtigen, an individual can authorise someone else to act on their behalf. The system is designed for people who cannot use DigiD (due to a lack of digital experience or illness, such as the elderly and children) to authenticate with the services of the Dutch public administration. Learn more about [DigiD Machtigen](https://logius.nl/domeinen/toegang/digid-machtigen). :::note Important DigiD Machtigen is only available when integrating with DigiD CombiConnect. ::: ### DigiD Next to DigiD Machtigen, DigiD CombiConnect allows you to offer standard DigiD login. To learn more high-level information about DigiD and setting it up as a standalone eID, visit the [**DigiD**](/identity-methods/digid/about-digid.mdx) page. ## Authentication flows DigiD CombiConnect is designed to provide end-users with alternative login routes depending on whether they authenticate for themselves through a standard DigiD flow or on behalf of another person through DigiD Machtigen as authorised guardians, legal representatives or parents on behalf of a child. :::tip Machtigen mandates plans Currently, DigiD Machtigen only entails voluntary mandates registered with Logius at [https://machtigen.digid.nl/](https://machtigen.digid.nl/). Note that Logius plans on adding legal representation and parental guardianship at a later stage. To learn more about this, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: When authenticating through your application, the screens should provide options to choose the appropriate flow. Therefore, you should design your application around these needs. For guidelines on how to design your screens and buttons, visit the [Style Guide](https://www.logius.nl/onze-dienstverlening/toegang/stijlhandleiding-aansluiten-toegang) on the Logius website. When integrating, you can control which authentication flow to trigger with specific query parameters. To learn more about how to build your authentication URLs, get started with the [DigiD CombiConnect Integration guide](/identity-methods/digid-combiconnect/integration/). ## Migrating from an existing DigiD integration If you have already implemented [DigiD with Signicat](/identity-methods/digid/) but would like to migrate to DigiD CombiConnect, for example to include DigiD Machtigen in your services, you are required to register for a new Logius connection number (aansluitnummer). For a CombiConnnect connection, you need to notify us and fill in the [request form](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Aansluitformulier-1-DigiD-dienst) available on the Logius website. In case of future changes to your CombiConncect connection, then you need to use the [Logius Change form](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-wijzigingsformulier). :::note Audits Normally, a change requires a new audit with Logius. However, you can request an exception, if your application has been audited before. Read more in the Logius [documentation](https://www.logius.nl/onze-dienstverlening/toegang/digid/ict-beveiligingsassessments-digid/hoe-werkt-het). ::: If you require any assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ## Useful links Websites: - [Logius website](https://www.logius.nl/) - [DigiD Machtigen website](https://machtigen.digid.nl/) - [DigiD website](https://www.digid.nl/) Logius documentation: - [DigiD documentation](https://www.logius.nl/onze-dienstverlening/toegang/digid/documentatie) - [Guidelines for login screens](https://www.logius.nl/onze-dienstverlening/toegang/stijlhandleiding-aansluiten-toegang) - [Logius | CombiConnect - Aansluitformulier voor één DigiD dienst](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Aansluitformulier-1-DigiD-dienst) - [Logius | CombiConnect - Wijzigingsformulier](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-wijzigingsformulier) - [Logius | ICT-beveiligingsassessments DigiD](https://www.logius.nl/onze-dienstverlening/toegang/digid/ict-beveiligingsassessments-digid) --- ## Attributes reference(Digid-combiconnect) You use DigiD CombiConnect to verify the end-user's identity and obtain relevant personal details about them. This page shows the end-user information you can retrieve with each authentication protocol. ## Available attributes ### BSN End-users authenticate with DigiD using their personal citizen service number (BSN). The BSN is available in the response from the authentication flow. Note that BSN corresponds to the national identity number (NIN) returned by other eIDs. ### DigiD Machtigen When a person logs in on-behalf of someone else, you can retrieve the BSN of both the guardian and the actual individual they are logging in for. Authentications with DigiD Machtigen will return an additional field in the response (`acting_nin` for OIDC or `actingNin` for the other protocols) containing the BSN of the person authorised to manage the end-user's affairs online. This is in addition to the BSN (returned in the `nin` object) of the actual individual. ## OIDC scopes and claims You can use the following scopes to request user information from an end-user using DigiD CombiConnect: :::CustomTable{columnWidths="20% 20% 20% 40%"} | Scope | OIDC Claim | Example | Description | |:------| :--------- | :----------- |:----------- | | `idp-id` | `idp_id` | `999999990` | Personal identifier set by the identity provider. In this case, it returns the BSN. | | `nin` | `nin` | `999999990` | National identification number (burgerservicenummer; BSN) of the end-user, consisting of 9 digits. | | | `nin_issuing_country` | `NL` | Issuing country of the national identity. | | | `nin_type` | `BSN` | The type of nation identification number. Always `BSN`. | | `acting-nin` | `acting_nin` | `000000009` | BSN of the person authorised to log in on behalf of the end-user. Consists of 9 digits. | ::: ### OIDC request examples To trigger an end-user authentication flow with OIDC, the URL could look like: ```sh https:///auth/open/connect/authorize? client_id= &response_type=code &redirect_uri= &scope=openid%20nin%20idp-id%20acting-nin &acr_values=idp:digid-combiconnect &prompt=login ``` After a successful authentication, you receive a server response with an access token and an ID token in the body of the response. An ID token is a JWT similar to `eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA` :::details What is a JWT? A JSON Web Token (JWT) consists of three parts separated by dots (`.`), which correspond to: - Header - Payload - Signature A JWT typically looks like: `xxxxx.yyyyy.zzzzz` ::: The decoded payload (data) of the ID token for DigiD CombiConnect would then look like: ```json { "iss": "https:///auth/open", "nbf": 1709652445, "iat": 1709652445, "exp": 1709653045, "aud": "", "amr": [ "external" ], "at_hash": "r99QeeZDCO4XHixurU_HTA", "sid": "5866A06...D1433A9649", "sub": "M8DuuHPYvP...Z0vsnZivrfFjs=", "auth_time": 1709652442, "idp": "digid", "idp_id": "999999990", "nin": "999999990", "nin_type": "BSN", "nin_issuing_country": "NL", "acting_nin": "000000009", "idp_issuer": "https:///saml/idp/metadata", "transaction_id": "94b2b88c-d2f7-5942-ff4f1cb966f8" } ``` :::tip ID Token with `nin` By default, the ID Token contains only the claims defined in the OIDC standard (standard scopes). Therefore, the `nin` is not included in the ID token you receive after authentications with DigiD CombiConnect. To receive the `nin` in the ID Token, go to your [OIDC client](https://dashboard.signicat.com/oidc-clients/) in the Signicat Dashboard and edit the **ID Token User data** in the **Advanced** > **Security** tab. Alternatively, you can fetch the `nin` from the UserInfo endpoint. ::: ### OIDC response example The response examples below show user information that could be contained in the ID Token or retrieved from the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. #### Example with standard DigiD authentication Scope: `openid idp-id nin`. ```json { "idp_id":"999999990", "nin":"999999990", "nin_type":"BSN", "nin_issuing_country":"NL", "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example with DigiD Machtigen authentication Scope: `openid idp-id nin acting-nin`. ```json { "idp_id":"999999990", "nin":"999999990", "nin_type":"BSN", "nin_issuing_country":"NL", "acting_nin": "000000009", "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` #### Example without additional scopes Scope: `openid`. ```json { "sub":"M8DuuHPYv...nZivrfFjs=", "idp_issuer":"https:///saml/idp/metadata" } ``` ## Authentication REST API attributes The Signicat Authentication REST API supports the following request attributes for DigiD: :::CustomTable{columnWidths="20% 20% 20% 40%"} | Attributes | Sub-field | Example | Description | | :------------ | :--------- | :--------- | :---------------- | | `idpId` | | `999999990` | Personal identifier set by the identity provider. | | `nin` | `value` | `999999990` | National identification number (BSN) of the end-user. | | | `issuingCountry` | `NL` | Issuing country of the national identity. | | | `type` | `BSN` | The type of nation identification number. Always `BSN`. | | `actingNin` | | `000000009` | National identification number (burgerservicenummer; BSN) of the person authorised to log in on behalf of the end-user. Consists of 9 digits. | ::: ### Authentication API response example Here is a section of the response showing the user information attributes: ```json ... "subject": { "id": "999999990", "idpId": "999999990", "nin": { "value": "999999990", "issuingCountry": "NL", "type": "BSN" }, "actingNin": "000000009", } ... ``` ## SAML 2.0 attributes Integrating with SAML 2.0, allows you to use the following request attributes for DigiD: :::CustomTable{columnWidths="33% 33% 33%"} | Attributes | Example | Description | | :---------- | :--------- | :------------- | | `idpId` | `999999990` | Personal identifier set by the identity provider. | | `nin` | `999999990` | National identification number (BSN) of the end-user. | | `nin.issuingCountry` | `NL` | Country issuing the national identity. | | `nin.type` | `BSN` | The type of nation identification number. Always `BSN`. | | `actingNin` | | `000000009` | National identification number (burgerservicenummer; BSN) of the person authorised to log in on behalf of the end-user. Consists of 9 digits. | ::: ### SAML 2.0 response example ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... HASHED_SUBJECT ENTITY_ID 999999990 NL BSN 000000009 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport https://was-preprod1.digid.nl/saml/idp/metadata ``` --- ## DigiD CombiConnect DigiD CombiConnect is a technical specification and interface to integrate DigiD and DigiD Machtigen into your digital services. DigiD CombiConnect is an architectural component to route your end-users to either: - **DigiD** is an electronic identification (eID) method in the Netherlands that allows citizens with a burgerservicenummer (BSN) to access the online services of organisations with a public function. - **DigiD Machtigen** (Authorisation) is a service for citizens to authorise someone else to act on their behalf. For example, a family member, a healthcare provider or a tax advisor. If you want to read more high-level documentation about DigiD CombiConnect before you start the integration, see [About DigiD CombiConnect](/identity-methods/digid-combiconnect/about-digid-combiconnect.mdx). :::note DigiD CombiConnect facts - Countries: Netherlands - Use cases: Authentication, Authorisation, authentication-based electronic signing - Supported protocols: OIDC, Authentication REST API, SAML 2.0 - Devices: Mobile, desktop - Key attributes: National identity number (BSN) - LoA: Basic, Low, Medium, High ::: ## Get started * [**Integration guide**](/identity-methods/digid-combiconnect/integration/): Follow step-by-step guides to integrate to DigiD CombiConnect * [**Attributes reference**](/identity-methods/digid-combiconnect/attribute-reference): Attributes and response examples per protocol ## Learn more * [**About DigiD CombiConnect**](/identity-methods/digid-combiconnect/about-digid-combiconnect): High-level description of how DigiD CombiConnect works ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Order certificates(Integration) :::warning Important To set up DigiD CombiConnect, you first need to start with the steps described in the [Initial preparations](/identity-methods/digid-combiconnect/integration/prerequisites.mdx) page. Without following those important steps you may experience delays, technical difficulties or even unnecessary expenses. ::: ## 1. Create a CSR in the Dashboard A **Certificate Signing Request (CSR)** contains identifying information about your organisation. When applying for a PKIo certificate, you need to create a CSR and share it with a Certificate Authority (CA). Doing this allows the CA to verify your business and issue a PKIo certificate. To create a CSR in the Signicat Dashboard, follow these steps: 1. Go to the **Signicat Dashboard** > [**Organisation management**](https://dashboard.signicat.com/org-mgmt/). 2. Select the account to create a CSR for. 3. In the account management page, select [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 4. In **Certificate Signing Requests**, select **Create**. 5. Fill in the fields in the form: :::CustomTable{columnWidths="25% 20% 30% 25%"} | Information | Distinguished Names | Description | Example | |:------|:------------|:------------|:------------| | Common name | `CN` | The [fully qualified domain name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to secure for your integration. | some.example.com | | Serial number | `SERIALNUMBER` | The [Organisation Identification Number (OIN)](https://www.logius.nl/domeinen/toegang/organisatie-identificatienummer) assigned by Logius to your organisation. This field is compulsory for eHerkenning certificates. | 0000000X123456780000 | | Organisation name | `O` | Registered legal name of your organisation. | Signicat AS | | Organisation unit | `OU` | Internal organisation department/division name | IT | | Country | `C` | The [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) where your organisation is registered. | NL | | Locality | `L` | Town, city, village name. | Amsterdam | | State or Province | `ST` | Province, region, county or state. | Noord-Holland | | Subject Alternative Names | `SAN` | Optional. Provide a FQDN like the Common Name (CN) field or leave empty. | some.example.com | ::: 6. Select **Create** to generate the Certificate Signing Request (CSR) based on the information you submitted. 7. Select **Download** to download the newly created CSR. A CSR is represented as a Base64 encoded string: ```bash -----BEGIN CERTIFICATE REQUEST----- ...Base64-encoded string... -----END CERTIFICATE REQUEST----- ``` Remember that you need to share the CSR with the Certificate Authority (CA) when you apply for a PKIo certificate, as explained in the next step below. ## 2. Purchase PKIo certificates :::tip What are PKIo certificates? PKIo certificates are Public Key Infrastructure (PKI) certificates used to cryptographically sign messages between Signicat and the network infrastructure of Logius. Learn more about PKIo certificates at [https://cert.pkioverheid.nl/](https://cert.pkioverheid.nl/) and [https://www.logius.nl/english/pkioverheid](https://www.logius.nl/english/pkioverheid). ::: PKIo certificates are required to connect to DigiD, DigiD CombiConnect or eHerkenning. To integrate successfully, you need to purchase and configure two separate certificates: 1. One PKIo certificate for sandbox (preproduction) 2. One PKIo certificate for production :::note Lead time Note that obtaining a new PKIo certificate may take up to *five* working days. ::: #### Supported PKIo certificate types The PKIo certificates must be of one of these types: - **Staat der Nederlanden - G4 Root Priv G-Other - 2024** (until 2039) - G4 Intm Priv G-Other LP - 2024 (recommended) - **Staat der Nederlanden Private Root CA - G1** (until 2028) - Staat der Nederlanden Private Services CA - G1 - **Staat der Nederlanden Root CA - G3** (until 2028) - Staat der Nederlanden Organization Services CA - 2023 - Staat der Nederlanden Organisatie Services CA - G3 #### Certificate providers You can purchase PKIo certificates from any of the Trust Service Providers (TSPs) approved by Logius. For a list of authorised providers, see the [PKIoverheidcertificaat aanvragen](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/pkioverheidcertificaat-aanvragen) page. :::warning Additional requirements for Digidentity certificates To purchase Digidentity certificates, Signicat must first generate the appropriate Certificate Signing Request (CSR) for you. Please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::info Purchase checklist When purchasing PKIo certificates, make sure that: 1. You only use the **Certificate Signing Request (CSR)** obtained in the Signicat Dashboard. If you purchase the certificates independently or without the CSR, your integration will fail. 2. You purchase two separate **PKIoverheid (PKIo)** certificates: one for the sandbox environment and one for the production environment. 3. The type of PKIo certificate is one of the [Supported PKIo certificate types](#supported-pkio-certificate-types). When purchasing a certificate, you should explicitly ask the provider to use the CSR you generated in the Signicat Dashboard. ::: You can find more instructions to guide you with purchasing PKIo certificates from a trusted provider on the Logius website at [PKIoverheid-certificaat aanvragen](https://www.logius.nl/domeinen/toegang/pkioverheidcertificaat-aanvragen). :::info New regulations The importance of certificates is increasing and regulations around certificates are changing. Learn more about the [new generation of PKIo certificates](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/wees-voorbereid-de-nieuwe-generatie-pkioverheidcertificaten-komen-eraan). ::: ## 3. Upload PKIo certificates in the Dashboard Once you have purchased and received the PKIo certificates from a certificate provider, you need to upload the *public* part of the certificates (`.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a PKIo certificate to the Signicat Dashboard, do the following: 1. Navigate to **Account management** > [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** to upload the PKIo certificate from your device. Alternatively, you can send us the new PKIo certificate either by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or by contacting your onboarding manager. :::note Certificate activation time Please allow up to 4 hours for the certificates to become active and ready for use. If you require expedited processing, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request priority handling. ::: :::tip Where to find PKIo certificates in the Signicat Dashboard When you upload a PKIo certificate, you store the (public) PKIo certificate in the Signicat Dashboard infrastructure. To view your certificates, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**eID Hub**](https://dashboard.signicat.com/auth). 2. In the left-side menu, navigate to **Advanced** > **Certificates**. 3. Here, you can review your active certificates and access more details, such as issuer and validity window. ::: ## Next step To continue your integration, proceed to the guide below: * [**4. Set up DigiD CombiConnect**](/identity-methods/digid-combiconnect/integration/setup): Choose a protocol and connect to DigiD CombiConnect --- ## Configure the Dashboard This page provides instructions to sign up with Signicat on the Signicat Dashboard and configure your account to prepare for the integration with DigiD CombiConnect. ## 1. Sign up to Signicat If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Create an [organisation](/docs/dashboard/organisation-management/organisations.mdx). ## 2. Accounts and environments When integrating with DigiD CombiConnect, you must first test and get approval for the pre-production account before you can proceed with the integration in a production account. Logius offers two separate environments for your integration with DigiD CombiConnect. Signicat matches this design with two separate types of accounts as displayed in the table below: :::CustomTable{tableName="Accounts and enviroments in DigiD CombiConnect" columnWidths="40% 60%"} | Logius environments | Signicat accounts | |------------|-------------| | Pre-production (test environment) | Sandbox account | | Production | Production account | ::: The subsection below guides you through your account configuration in the Signicat Dashboard. ### 2.1 Create a sandbox account To test DigiD CombiConnect in the pre-production environment, you need to create a sandbox account with a custom domain in the Signicat Dashboard. To do this: 1. Go to the [Signicat Dashboard](https://dashboard.signicat.com/). 2. Create a sandbox account. For detailed instructions, see the [Create an account](/docs/dashboard/organisation-management/accounts.mdx#create-an-account) section. :::tip Existing customers If you are an existing Signicat customer, you may reuse a sandbox account that you have previously created. ::: ### 2.2 Add a custom domain :::warning Required Note that you must add a *custom* domain. Accounts with a Signicat subdomain (for example, `mycompany.signicat.com`) do not support connections with DigiD CombiConnect. ::: To configure your account with a custom domain, do the following: 1. Go to the **Signicat Dashboard** > [**Organisation management**](https://dashboard.signicat.com/org-mgmt/). 2. Select the account where to add the new domain. Then, select **Domains**. 3. Select **+ Add domain** at the top right of the screen. 4. Add a **custom domain**. For detailed instructions, see the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. You can add a custom domain with either Signicat-managed or self-managed certificates. :::tip Using Let's Encrypt certificates If you wish to connect with [Let's Encrypt](https://letsencrypt.org/) certificates as TLS server certificates for DigiD CombiConnect, then you must use a `.nl` domain. Learn more in the [Logius documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie/factsheet-dv-en-ov-certificaten-bij-digid). ::: Once you have created a sandbox account with a custom domain, you can proceed to create a Certificate Signing Request (CSR). This is necessary to obtain PKIo certificates for DigiD CombiConnect. ## Next step * [**3. Order certificates**](/identity-methods/digid-combiconnect/integration/certificates): Create a CSR and purchase PKIoverheid certificaes --- ## Integration guide(3) To establish a connection with DigiD CombiConnect through Signicat, you first need to meet a few requirements like signing agreements and complying with Logius requirements. Once completed, you can start integrating with Signicat in the Dashboard. :::info Is DigiD CombiConnect for you? Note that DigiD CombiConnect is only available for service providers operating in the public domain. ::: The guides below contain all the necessary steps to prepare, set up and deploy your DigiD CombiConnect integration to production. ## Guides * [**1. Initial preparations**](/identity-methods/digid-combiconnect/integration/prerequisites): Sign agreements with Signicat and Logius * [**2. Configure the Dashboard**](/identity-methods/digid-combiconnect/integration/dashboard-configuration): Sign up and configure the Signicat Dashboard * [**3. Order certificates**](/identity-methods/digid-combiconnect/integration/certificates): Create a CSR and purchase PKIoverheid certificates * [**4. Set up DigiD CombiConnect**](/identity-methods/digid-combiconnect/integration/setup): Choose a protocol and connect to DigiD CombiConnect * [**5. Go to production**](/identity-methods/digid-combiconnect/integration/production): Connect to the DigiD CombiConnect production account --- ## Initial preparations(Integration) Before you can start integrating with the Signicat solution for DigiD CombiConnect, your organisation needs to complete a series of preparatory steps, such as signing agreements, obtaining certificates, understanding and preparing for the security and audit requirements. Note that the application process requires communication between your organisation and Logius, the provider of DigiD CombiConnect, and also between your organisation and Signicat's onboarding team. :::warning Pre-production and production It is important to note that you must first integrate in a pre-production/test environment that you share with Logius for review. Then, after you have received approval on your pre-production setup, you may start integrating with DigiD CombiConnect in a production environment. ::: This page contains information about the onboarding steps you need to follow ahead of implementing DigiD CombiConnect in your application. ### Overview :::note Checklist for DigiD CombiConnect ::: ## 1. Sign agreements with Signicat To get started with onboarding, you need sign contractual agreements with us. These are necessary to grant you access to our services. In particular, you need to sign: 1. An agreement contract 2. A data processing agreement (DPA) (signed by a legal representative) When you are ready, contact one of our digital experts: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) :::warning Which organisations can apply Note that integration with DigiD CombiConnect is restricted to organisations offering services in the public domain such as the government, educational institutes, healthcare institutions or pension funds. ::: ## 2. Comply with Logius requirements Note that your organisation must comply with the mandatory security and infrastructure requirements of Logius. In particular, your connection needs to meet the criteria specified in: - [DigiD ICT security guidelines for web applications](https://www.logius.nl/onze-dienstverlening/toegang/digid/ict-beveiligingsassessments-digid/documentatie/norm-ict-beveiligingsassessments-digid) - [Checklist aansluiten](https://logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen) ### Assessment and audit Your DigiD CombiConnect connection must undergo an official assessment by an external and certified DigiD auditor within two months after it is live in production. Your organisation should arrange the audit during the integration process. :::info Annual assessments Note that organisations connected to DigiD CombiConnect must also undergo annual ICT security assessments. You can find more information in the [ICT security assessments](https://www.logius.nl/onze-dienstverlening/toegang/digid/ict-beveiligingsassessments-digid) page on the Logius website. ::: :::note About Signicat and DigiD The Signicat integration of DigiD CombiConnect undergoes a yearly assessment where we supply our DigiD Generieke Rapporten voor de Serviceorganisatie (RSO, formerly TPM) certificate to our service providers. You should use the Signicat RSO certificate in your audit with Logius. ::: ## 3. Register with RvIG Registration with the Dutch governmental organisation Rijksdienst voor Identiteitsgegevens (RvIG) is required when organisations plan on processing a person's BSN attribute. As part of the assessment, RvIG checks whether your organisation qualifies to request a person's BSN during authentication. You can find the application form for BSN eligibility in the [Aanvraagformulier Toetsing BSN-gerechtigdheid](https://www.rvig.nl/aanvraagformulier-bsn-gerechtigdheid). ## Next step * [**2. Configure the Dashboard**](/identity-methods/digid-combiconnect/integration/dashboard-configuration): Sign up and configure the Signicat Dashboard --- ## Go to production(Integration) :::warning Important To set up DigiD CombiConnect in production, you first need to set up a connection in a pre-production (sandbox) environment and get it approved by Logius. So, make sure you have completed the steps, as described in the [Setup up DigiD CombiConnect](/identity-methods/digid-combiconnect/integration/setup.mdx) for your pre-production environment. ::: ## Prerequisites Before you can prepare your application for production, you must have completed the prerequisite steps: - [Purchase a PKIoverheid certificate](/identity-methods/digid-combiconnect/integration/certificates.mdx) for production environments. - Get your [pre-production setup](/identity-methods/digid-combiconnect/integration/setup.mdx) approved by Logius. ## 1. Create a production account To connect to DigiD CombiConnect in production, you need to set up a production account with a custom domain in the Signicat Dashboard. You can always reuse a production account that you created previously. To create a new production account, do the following: 1. Go to **Signicat Dashboard** > [Organisation management](https://dashboard.signicat.com/org-mgmt/). 2. Select **Add Account**. 3. Enter the name of your account under **Account Name** and tick the box for **Production account**. Note that this requires that already completed your company's onboarding in the Dashboard. 4. Select **Create** to create the new account. In the next screen, select **Add new domain** to add a custom domain. ### Add a custom domain To add a custom domain, follow the instructions for [Custom domains](/docs/dashboard/organisation-management/domains/custom/). Then, return to this page to continue with the integration. :::warning Custom domain Note that you must add a *custom* domain. Accounts with a Signicat subdomain (for example, `mycompany.app.signicat.com`) cannot be used to connect to DigiD. ::: :::tip Using Let's Encrypt certificates If you wish to use [Let's Encrypt](https://letsencrypt.org/) certificates as TLS/SSL server certificates for DigiD, you must use a `.nl` domain. Learn more in the [Logius documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie/factsheet-dv-en-ov-certificaten-bij-digid). ::: ## 2. Upload PKIo certificates :::warning Order certificates This step assumes that you have already purchased a PKIoverheid certificate for production. Learn how in the [Order certificates](/identity-methods/digid-combiconnect/integration/certificates.mdx) guide. ::: Once you have purchased and received the PKIo certificates from a certificate provider, you need to upload the *public* part of the certificates (`.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a PKIo certificate to the Signicat Dashboard, do the following: 1. Navigate to **Account management** > [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** to upload the PKIo certificate from your device. Alternatively, you can send us the new PKIo certificate either by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or by contacting your onboarding manager. :::note Certificate activation time Please allow up to 4 hours for the certificates to become active and ready for use. If you require expedited processing, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request priority handling. ::: :::tip Where to find PKIo certificates in the Signicat Dashboard When you upload a PKIo certificate, you store the (public) PKIo certificate in the Signicat Dashboard infrastructure. To view your certificates, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**eID Hub**](https://dashboard.signicat.com/auth). 2. In the left-side menu, navigate to **Advanced** > **Certificates**. 3. Here, you can review your active certificates and access more details, such as issuer and validity window. ::: ## 3. Set up a connection Follow the steps 1-6 in the [Set up DigiD CombiConnect](/identity-methods/digid-combiconnect/integration/setup.mdx) guide. Then, come back to this page to activate your connection in production. ## 4. Activate your connection Submit a request for activation of your connection to the DigiD CombiConnect production environment in the [DigiD Wijzigingsformulier](https://www.logius.nl/domeinen/toegang/digid/wijzigingsformulier-digid). In the form, select "Ik wil mijn productieaansluiting activeren". ## 5. Ask Logius to approve your connection After you set up the connection in production, you need to test it and submit a request for approval by Logius. - Test your implementation using the [Checklist for connecting to DigiD](https://www.logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen). - Apply changes to meet the requirements. - Ask Logius to verify your integration by requesting a connection test with the form [CombiConnect - Aansluitformulier voor één DigiD dienst](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Aansluitformulier-1-DigiD-dienst). ## 6. Audit and assessment Your DigiD CombiConnect integration in production should adhere to security standards to ensure secure end-user authentication. Logius performs audits and checks to ensure your infrastructure and connection comply with such requirements. Your DigiD CombiConnect integration must undergo an official assessment by an external and certified DigiD CombiConnect auditor within two months after your application is live in production. Additionally, organisations that use DigiD CombiConnect must conduct an annual IT security assessment. Arrange the audits according to the specifications in the DigiD [ICT-beveiligingsassessments](https://www.logius.nl/domeinen/toegang/digid/ict-beveiligingsassessments-digid) guide. :::note Signicat RSO certificate Signicat, as a third-party provisioning services for DigiD CombiConnect, undergoes a Rapporten voor de Serviceorganisatie (RSO, formerly TPM) yearly assessment. For this we to plan the RSO audit as early as possible in the year. We can also provide you with our DigiD Generieke RSO certificate to use in your audit. Note that the yearly required assessment planning for municipalities in NL and for DigiD CombiConnect occurs at different times of the year and might lead to some delays. Therefore, we recommend you plan sufficient time around the assessment with municipalities' own audits. ::: ## Useful links - [Logius - Aansluiten op DigiD](https://www.logius.nl/domeinen/toegang/digid/aansluiten-wijzigen) - [Logius - DigiD](https://www.logius.nl/domeinen/toegang/digid) - [DigiD documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie) --- ## Set up DigiD CombiConnect This page shows how to set up a DigiD CombiConnect connection through Signicat. ## Prerequisites Before you continue, make sure that you have: 1. Followed the [Initial preparations](/identity-methods/digid-combiconnect/integration/prerequisites.mdx). 2. Signed up and configured the [Signicat Dashboard](/identity-methods/digid-combiconnect/integration/dashboard-configuration.mdx). 3. [Purchased PKIoverheid certificates](/identity-methods/digid-combiconnect/integration/certificates.mdx) for both pre-production and production environments. ## 1. Add DigiD CombiConnect in the Dashboard When you want to use an eID, you first need to activate it in the Signicat Dashboard. To do this for DigiD CombiConnect, follow these steps: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Click **+ Add new** in the top right. 3. Choose the eID from the list. Then, fill in any required configuration and click **Add**. 4. Now, review that the eID is available and displayed as "Active" in the eIDs page. :::note Cannot activate DigiD CombiConnect? If you cannot activate DigiD CombiConnect or require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: ### eID configuration DigiD CombiConnect Dashboard settings In the DigiD CombiConnect configuration page, you can adjust the following (optional) settings: :::CustomTable{columnWidths="20% 20% 60%"} | Setting | Level | Description | |:--------|:--------|:----------- | | Entity index (0-9999) | Advanced | Optional. A unique index for the EntityID if you have multiple connections with Logius. Default values: `9000` (sandbox), `1` (production). **Note**: After updating the index value, you need to save the configuration changes before you can download the updated metadata from the Dashboard and provide it to Logius. | | Include only when scoped | Advanced | Optional. If ticked, DigiD CombiConnect will _not_ be displayed on the eID selection screen by default, unless you specify it with [IdP scoping](/docs/eid-hub/concepts/idp-scoping/). This allows you pass eID(s) as a query parameter in your request to control which eIDs the end-users can choose for authentication. This is useful when multiple eIDs are active in your account and you only want to offer a subset to your end-users. | | Select attribute filter | Advanced | Optional. Select an attribute filter to control which attributes to include, or exclude, from the response. To create attribute filters in the Signicat Dashboard, go to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Response attribute mapping | Advanced | Optional. Allows you to map the name of any attribute in the response to a custom name of choice. | ::: Adjust the settings as necessary and click **Save** to apply the changes. ## 2. Get Signicat metadata When you activate DigiD CombiConnect in the Signicat Dashboard, you can download the Signicat SAML metadata (in XML format). To get the metadata file: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **DigiD CombiConnect** from the list of active eIDs. 3. Select **Get Signicat metadata** to download the XML file to your device. :::note Signicat metadata You need to provide the Signicat metadata when applying for DigiD CombiConnect with Logius in the next step. ::: ## 3. Request a DigiD CombiConnect connection from Logius To connect to DigiD CombiConnect, you need to send a request to Logius. In the application form, you need to provide Signicat's metadata that you obtained in the previous step. Follow these steps: 1. Request a CombiConnect connection by filling in the [CombiConnect - Aansluitformulier](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Aansluitformulier-1-DigiD-dienst). 2. Provide details about your service by filling in the [CombiConnect - Dienstgegevensformulier](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Dienstgegevensformulier-1-DigiD-dienst). 3. To add DigiD Machtigen, you need to submit a change request by filling in the [CombiConnect - Wijzigingsformulier](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-wijzigingsformulier) where you request to add DigiD Machtigen to your existing DigiD CombiConnect connection. According to the Logius [Roadmap](https://www.logius.nl/domeinen/toegang/digid/aansluiten-wijzigen), you receive connection details for access to a DigiD CombiConnect environment within five working days. However, note that Logius has a waiting list for processing connections to CombiConnect and gives priority to certain sectors, such as healthcare. You should also consider that you need to prepare your organisation and application for processing the functionality and data from DigiD Machtigen. :::note Environments Note that you will need to perform this step both for pre-production and, after pre-production is approved, again for production. ::: ## 4. Set up a connection with a protocol To establish a connection between DigiD CombiConnect and your application, you need to use an authentication protocol. Note that you only need to connect to Signicat eID and Wallet Hub servers. Signicat handles the connection with DigiD CombiConnect separately, therefore acting as a message broker between your application and DigiD CombiConnect. ### Choose a protocol :::tip Supported authentication protocols Signicat supports the standard **OpenID Connect (OIDC)** and **SAML 2.0** protocols. In addition, we offer our bespoke **Signicat Authentication REST API**. The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API. To learn more about these authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: ### Set up the protocol For information on how to set up the different protocols, see the [eID and Wallet Hub - Quick start guide](/docs/eid-hub/quick-start/). ## 5. Build the authentication request To initiate an authentication flow, you need to build an authentication URL. This is the DigiD authorisation server where you route the end-user to start the authentication flow and log in with their credentials. How you build the authentication URL depends on these factors: - The authentication protocol you use in the integration: OIDC, SAML or Authentication REST API. - The authentication flow chosen by the end-user: DigiD or DigiD Machtigen. ### DigiD and DigiD Machtigen authentication flows You craft your authentication request differently depending on the authentication flow chosen by your end-user. The possible flows are: - **(Standard) DigiD**: Applies to end-users who want to log in on their own. - **DigiD Machtigen (Authorisation)**: Applies to end-users authorised to log in on behalf of another individual. In your application, you need to provide options for each of these flows, for example by displaying separate buttons. The end-user's choice determines the authentication request that your application builds and sends to Signicat, as explained in the next section. #### Obtain the flow identifiers First, you need to retrieve the flow identifier that matches the flow type. Flow identifiers allow you route your end-users to the appropriate authentication flow, either (Standard) DigiD or DigiD Machtigen (Authorisation). A flow identifier follows this syntax: `urn:nl-eid-gdi:1.0:::entities:"`. :::tip Understanding the flow code The `FLOW_CODE` is a static value that identifies the type of DigiD service you are using. It is determined by the specific metadata URL you access. For the flows described here, the codes are: - (Standard) DigiD: `TD` - DigiD Machtigen: `BVD` ::: :::tip Understanding the EntityID The `ENTITY_ID` is a placeholder for the Entity Index (for example, `9000`). This value is configurable in the Signicat Dashboard using the **Entity index (0-9999)** field in your connection settings, as explained in the [eID configuration](#eid-configuration) section. Default values: - Sandbox accounts: the default Entity Index is `9000`. - Production accounts: the default Entity Index is `0001`. You can specify a different index for your entity using the **Entity index (0-9999)** field. This is particularly useful if you have multiple connections registered with Logius and need to distinguish them. **Important**: If you update the index, you must save the configuration changes. After saving, you can download the updated metadata from the Dashboard and provide it to Logius. ::: Follow the instructions below to obtain the flow identifier for the appropriate DigiD authentication flow. ##### (Standard) DigiD flow identifiers To obtain the flow identifiers for Standard DigiD connections, follow these steps: 1. Go to the respective metadata page for your environment: - **Pre-production**: [https://api-preprod1.digid.nl/saml/v4/entrance/metadata](https://api-preprod1.digid.nl/saml/v4/entrance/metadata) - **Production**: [https://api.digid.nl/saml/v4/entrance/metadata](https://api.digid.nl/saml/v4/entrance/metadata) 2. In the `EntityDescriptor` element, find the `entityID` attribute and copy its value. This is the flow identifier you need to use as a query parameter in your request. The flow identifier will have a format similar to this: ``` urn:nl-eid-gdi:1.0:TD:00000004183317817000:entities:9000 ``` Remember that the flow code for Standard DigiD flows is `TD`. ##### DigiD Machtigen (Authorisation) flow identifiers To obtain the flow identifiers for DigiD Machtigen connections, follow these steps: 1. Go to the respective metadata page for your environment: - **Pre-production**: [https://api-preprod1.digid.nl/saml/v4/bvd/metadata](https://api-preprod1.digid.nl/saml/v4/bvd/metadata) - **Production**: [https://api.digid.nl/saml/v4/bvd/metadata](https://api.digid.nl/saml/v4/bvd/metadata) 2. In the `EntityDescriptor` element, find the `entityID` attribute and copy its value. This is the flow identifier you need to use as a query parameter in your request. The flow identifier will have a format similar to this: ``` urn:nl-eid-gdi:1.0:BVD:00000004003214345001:entities:9000 ``` Remember that the flow code for DigiD Machtigen flows is `BVD`. #### How to build your request To specify which flow to use for authentication, you need to pass the flow identifiers as a query parameter in your request, similarly to how you would specify the eIDs with [IdP scoping](/docs/eid-hub/concepts/idp-scoping/). {/* In OIDC, you can specify the flow you want to trigger with the `acr_values` parameter in your authorisation request. In particular, use the `idp` key of the `acr_values` query parameter with the format `acr_values=idp:digid-combiconnect, `. Note that you need to add an empty For example, to trigger an authentication with DigiD Machtingen, the authorisation request could look like this: ```curl {9} https:///auth/open/connect/authorize? &client_id= &response_type= &redirect_uri= &scope= &state= &code_challenge=ABC123 &code_challenge_method=S256 &acr_values=idp:digid-combiconnect, urn:nl-eid-gdi:1.0:BVD:00000004003214345001:entities:9000 ``` To learn more about `acr_values`, see the [acr_values](/docs/eid-hub/oidc/oidc-implementation.mdx#acr_values) documentation. */} :::note Requests with OIDC or Authentication REST API For instructions on how to specify the flow with OIDC or the Authentication REST API, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: When using SAML, you can specify the flow you want to offer in the `ProviderID` property of the `IDPEntry` field, as shown below: ```xml {8-12} ENTITY_ID ``` {/* When using the Signicat REST API, specify the eIDs you want to offer in the `allowedProviders` field in the payload of the request to the [CreateSession](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, to display Email OTP and FTN to the end-user in the eID selection screen, use: ```json ... "allowedProviders": [ "digid-combiconnect" ], ... ``` */} ## 6. Use scopes and attributes To learn more about attributes, scopes and claims supported by each authentication protocol, visit the [Attributes reference](/identity-methods/digid-combiconnect/attribute-reference.mdx) page. {/* ### Control the LoA You must set the minimum LoA you require during authentication based on security level, type of data exchanged and risk. Read the guidelines for configuring the LoA at [Betrouwbaarheidsniveaus digitale dienstverlening](https://www.forumstandaardisatie.nl/onderwerpen/veilig-internet/betrouwbaarheidsniveaus). */} ## 7. Get your pre-production setup approved After you set up the pre-production web/mobile service connection, you need to test it and submit a request for approval by Logius. Here are the steps to follow: - Test your implementation using the [Checklist for connecting to DigiD](https://www.logius.nl/domeinen/toegang/digid/documentatie/checklist-aansluiten-op-digid-en-digid-machtigen). - Apply changes to meet the requirements. - Ask Logius to verify your integration by requesting a connection test with the form [CombiConnect - Aansluitformulier voor één DigiD dienst](https://www.logius.nl/domeinen/toegang/digid/Combiconnect-Aansluitformulier-1-DigiD-dienst). After Logius approves your pre-production connection, you are ready to integrate with DigiD CombiConnect in production. ## Next step * [**5. Go to production**](/identity-methods/digid-combiconnect/integration/production): Connect to the DigiD CombiConnect production account --- ## About eHerkenning Businesses and other organisations often need to deal with the government, local authorities or other official bodies. eHerkenning is the most secure way to access public services online and the only Dutch eID that allows users to act on behalf of a company. By providing online identification, eHerkenning enables its users to exchange confidential information with other organisations in a secure way. :::tip Who can use it Service providers in the Netherlands can integrate with eHerkenning to allow users to log in on behalf of their organisation. ::: The Signicat eID and Wallet Hub allows you to connect your online services directly to eHerkenning. Using the eID and Wallet Hub, you can determine per service which reliability level of eHerkenning is applicable to the service type. ## Key features The following features apply to eHerkenning: * The only Dutch eID that allows users to act on behalf of their company. * All Dutch government bodies _must_ support eHerkenning when offering online services for companies. * Supports three different [Levels of Assurance (LoA)](#levels-of-assurance). ## eHerkenning specifications :::tip Combining public and private eHerkenning specifications are created by the Dutch Government but with the know-how of private technology companies. Any private party that enters eHerkenning must comply with a strict set of security requirements. ::: ## What is a service? The public or government body that the end-user log in to is the *service*; for example, applying for an energy label, applying for subsidy, submitting taxes, parking permits, eLoket, pension plans, and many more. ## eHerkenning eIDAS The main purpose of eHerkenning is to allow Dutch citizens and businesses to do business online with the government. However, eHerkenning also supports electronic identification from other European login methods, in line with the European eIDAS Regulation. :::details What is eIDAS? eIDAS is the acronym for "electronic IDentification, Authentication and trust Services". The eIDAS regulation facilitates secure cross-border identification in the EU by establishing a framework for digital identity and authentication. ::: If you are a service provider with a public task, you are obliged to accept logins coming from other European eIDs through eHerkenning. Signicat offers eHerkenning with eIDAS support on request. You integrate with eIDAS in the same way as you do with eHerkenning but you must request eIDAS as an extra feature during onboarding. To learn more about eHerkenning and eIDAS, visit the [eHerkenning website - Clients in Europe (eIDAS)](https://www.eherkenning.nl/en/service-providers/clients-in-europe-eidas). ## Levels of Assurance eHerkenning offers the following Levels of Assurance (LoA): - **EH2+** (eIDAS Low): Login with username, password and additional 2FA method: SMS or PIN code. - **EH3** (eIDAS Substantial): Login with username, password and additional SMS code, PIN code (token), or an app with a QR code. - **EH4** (eIDAS High): Login with a PKIo certificate (a digital signature) or 2FA. A PKI certificate allows users to communicate securely online with Dutch banks and the tax administration. :::note Note When using eHerkenning through the eIDAS network, note that the LoA of the European eID of the end-user takes priority over the LoA defined in your online service. ::: ## Additional resources Learn more about eHerkenning from official sources: * [eHerkenning website](https://www.eherkenning.nl) * [LoA for eHerkenning](https://www.eherkenning.nl/en/levels-of-assurance) ## Next steps When you are ready to start integrating eHerkenning with the Signicat eID and Wallet Hub, follow our integration guides: * [**Integration guides**](/identity-methods/eherkenning/integration/): Learn how to set up, configure and test the integration --- ## eHerkenning attributes in Authentication REST API This page contains information about the user attributes that you can request and retrieve from eHerkenning when using the [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) as an authentication protocol. :::tip Attribute glossary To learn more about the properties of the data available through eHerkenning, visit the [Attribute glossary](/identity-methods/eherkenning/attributes-reference/glossary/) page. ::: ## Attributes table eHerkenning provides the following data: :::CustomTable | Attribute | Example | Description | Source | |:----------------|:-------------------|:---------------------------|:------------| | `idpId` | See note below \* | The raw (unhashed) value of the subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions.| eHerkenning | | `firstName` | Jane | The first name(s) of the end-user. | eHerkenning/eIDAS | | `lastName` | Doe | The surname of the end-user. | eHerkenning/eIDAS | | `dateOfBirth` | 1986-01-25 | The date of birth of the end-user in the format `YYYY-MM-DD`. | eHerkenning/eIDAS | | `gender` | U | The gender of the end-user. Allowed values are: `M` (male), `F` (female), `U` (unknown).| eIDAS | | `phoneNumber` | tel:+31203051900 | The registered phone number of the end-user in the format `tel:+ `. ([ RFC3966](https://tools.ietf.org/html/rfc3966)) | eIDAS | | `email` | jane.doe@example.com | The email address of the end-user. | eHerkenning/eIDAS | | `placeOfBirth` | Amsterdam | The place of birth of the end-user (string max 40). | eIDAS | | `nin` | 123456789 | The National Identification Number (NIN) associated with the end-user. | eHerkenning/eIDAS | | `chamberOfCommerce` | 12345678 | The Chamber of Commerce number (Kamer van Koophandel, KvK) of the organisation. The KvK number consists of 8 digits. | eHerkenning | | `eherkenningIntermediatekvkNr` | 87654321 | The Chamber of Commerce (KvK) number of an intermediary company involved in the eHerkenning process. Applies to chain authorisation. | eHerkenning | | `eherkenningVestigingsNr`| 123456789012 | The establishment number or branch number ([Vestigingsnummer](https://www.kvk.nl/en/about-the-business-register/branch-number/) in Dutch) of the organisation. Each branch of a business or legal entity in the Business Register (Handelsregister) has a unique 12-digit branch number. | eHerkenning | | `eherkenningRsin` | 987654321 | The Legal Entities and Partnerships Identification Number ([RSIN](https://www.kvk.nl/en/about-the-business-register/rsin-number/): Rechtspersonen en Samenwerkingsverbanden Informatienummer) associated with the organisation. Consists of 9 digits. | eHerkenning | | `eherkenningProbasNr` | PROBAS-00123 | A unique identifier for the organisation in the PROBAS database. The PROBAS number is issued by the Tax Authorities to organisations or persons that are not registered in the Business Register (Handelsregister), such as embassies and consulates. The PROBAS number is registered in the PROBAS register which is managed by the Ministry of Foreign Affairs. | eHerkenning | | `eherkenningTrrBd` | 987654321 | The top-level registration number used in eHerkenning for identifying the individual. | eHerkenning | | `eherkenningIntermediateTrrBd` | 123456789 | An intermediate registration number within the eHerkenning system. | eHerkenning | | `eherkenningPseudo`| See note below \* | The specific pseudonym identifier. | eHerkenning | | `eherkenningPseudoID` | | The PseudoID is used to uniquely identify a natural person. It is a service provider-specific persistent pseudonym that is encrypted specifically per service provider (that is your organisation) for privacy reasons. The PseudoID is always the same for a specific end-user, regardless of the Attesting Party used for authentication. It is hashed and Base64 encoded. | eHerkenning | | `eherkenningServiceID`| urn:etoegang:DV:00000000000000000000:services:1010 | An identifier representing a specific service within the eHerkenning framework.| eHerkenning | | `eherkenningServiceUUID` | d8f71022-789b-456c-abc1-2f1234567890 | The ServiceUUID is a universally unique identifier (UUID) of a service that is unique in the context of the network, but not linked to one service provider. | eHerkenning | | `organisationName` | Example BV | The official name of the organisation. | eHerkenning | | `eherkenningIntermediate OrganisationName` | InterExample BV | The name of the organisation acting as an intermediary in eHerkenning. Applies to chain authorisation. Format is string of max length 200. | eHerkenning | | `initials` | J | The initials of the end-user's first name(s). | eIDAS | | `familyNameInfix` | de| The infix or preposition in the user's surname, common in some naming conventions such as `van` or `de`. | eIDAS | | `18OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 18 years old. Possible values: `true` or `false`. | eIDAS | | `16OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 16 years old. Possible values: `true` or `false`. | eIDAS | | `12OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 12 years old. Possible values: `true` or `false`. | eIDAS | | `65OrOlder` | false| A Boolean attribute indicating whether the end-user is at least 65 years old. Possible values: `true` or `false`. | eIDAS | | `organisationVatRegistrationNumber` | NL123456789B01 | The VAT registration number of the organisation. | eHerkenning | | `organisationTaxReferenceNumber` | 123/ABC/456 | The tax reference number assigned to the organisation. | eHerkenning | | `organisationKvkNr` | 87654321 | The registration number of the organisation at the Dutch Chamber of Commerce. | eHerkenning | | `organisationLegalEntityIdentifier` | 5493001KJTIIGC8Y1R12 | The legal entity identifier (LEI) of the organisation. | eHerkenning | | `organisationEori` | NL123456789012 | The Economic Operators Registration and Identification (EORI) number of the organisation. | eHerkenning | | `organisationSeed` | 12345ABCD6789EFGH | The Single European Electronic Data (SEED) number for the organisation. | eHerkenning | | `organisationSic` | 62020 | The [Standard Industrial Classification (SIC)](https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list) code representing the industry of the organisation. | eHerkenning | | `organisationPostalCode` | 1012WX | The postal code for the organisation's address. | eHerkenning | | `organisationHouseNumber` | 123 | The house number of the organisation's registered address. | eHerkenning | | `organisationHouseNumberSuffix` | A | The suffix of the house number, if applicable. | eHerkenning | | `organisationPoBox` | 5678 | The postal office box number of the organisation, if applicable. | eHerkenning | | `organisationStreetName` | Main Street | The street name of the organisation's registered address. | eHerkenning | | `organisationLocatorDesignator` | Unit 3 | An additional designator to locate the address, such as "Unit" or "Suite". | eHerkenning | | `organisationLocatorName` | Innovation Centre | The name of a building or facility at the organisation's address. | eHerkenning | | `organisationAddressArea` | Midtown | A sub-area or neighbourhood within the organisation's city. | eHerkenning | | `organisationCity` | Amsterdam | The city where the organisation is located. | eHerkenning | | `organisationRegion` | North Holland | The region or province where the organisation is located. | eHerkenning | | `organisationCountryCode` | NL | The two-letter ISO country code of the organisation's location. | eHerkenning | | `birthName` | Jane Marie Doe | The full birth name of the individual. | eHerkenning | | `eherkenningFirstName NonTransliterated` | Ян | The first name of the individual in its original script (non-transliterated). | eHerkenning | | `eherkenningLastName NonTransliterated` | Иванов | The last name of the individual in its original script (non-transliterated). | eHerkenning | | `eherkenningFirstNameAtBirth` | Jan | The first name of the individual at birth. | eHerkenning | | `eherkenningLastNameAtBirth` | Jansen | The last name of the individual at birth. | eHerkenning | ::: \* **Pseudonym example:** `ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890` ## Examples ### Request example To create a session using the Authentication REST API, you send a POST request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint of the Authentication REST API. This is `https://api.signicat.com/auth/rest/sessions`. You define the parameters of the session in the payload of the request. For example: ```json { "allowedProviders": [ "eherkenning" ], "flow": "redirect", "requestedAttributes": [ "idpId", "firstName", "lastName", "dateOfBirth", "gender", "phoneNumber", "email", "placeOfBirth", "nin", "chamberOfCommerce", "eherkenningIntermediatekvkNr", "eherkenningVestigingsNr", "eherkenningRsin", "eherkenningProbasNr", "eherkenningPseudo", "eherkenningPseudoID", "eherkenningServiceID", "eherkenningServiceUUID", "organisationName", "eherkenningIntermediateOrganisationName", "initials", "familyNameInfix", "18OrOlder", "16OrOlder", "12OrOlder", "65OrOlder", ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` ### Response example The following is an example of a response showing the end-user information attributes: ```json { ... "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56", "status": "SUCCESS", "provider": "eherkenning", "subject": { "id": "X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=", "idpId": "E0DA125456E34014919EC26C5B1E6D9A8A5F7F2663A14C4D98BB6ADB3426FF09", "firstName": "Jane", "initials": "J.", "lastName": "Doe", "familyNameInfix": "de", "dateOfBirth": "1980-01-15", "gender": "U", "phoneNumber": "+31612345678", "email": "jane.doe@example.com", "placeOfBirth": "Amsterdam", "nin": "123456789", "18OrOlder": true, "16OrOlder": true, "12OrOlder": true, "65OrOlder": false, "chamberOfCommerce": "12345678", "eherkenningIntermediatekvkNr": "87654321", "eherkenningVestigingsNr": "123400567890", "eherkenningRsin": "987654321", "eherkenningProbasNr": "PROBAS-00123", "eherkenningPseudo": "pseudo-org-12345", "eherkenningPseudoID": "pseudo-id-67890", "eherkenningServiceID": "service-001", "eherkenningServiceUUID": "d8f71022-789b-456c-abc1-2f1234567890", "organisationName": "Example BV", "eherkenningIntermediateOrganisationName": "Intermediate Services BV" } ... } ``` --- ## eHerkenning attributes in OIDC This page contains information about the user attributes that you can request and retrieve from eHerkenning when using [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) as an authentication protocol. :::tip Attribute glossary To learn more about the properties of the data available through eHerkenning, visit the [Attribute glossary](/identity-methods/eherkenning/attributes-reference/glossary/) page. ::: ## Attributes table eHerkenning provides the following data: :::CustomTable{columnWidths="10% 10% 10% 60% 10%"} | Scope | OIDC Claim | Example | Description | Source | |---------------------|---------------|--------------|--------------|-------------| | `idp-id` | `idp-id` | See note below \* | The raw (unhashed) value of the subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions. | eHerkenning | | `profile` | `given_name` | Jane | The first name(s) of the end-user. | eHerkenning/eIDAS | | `profile` | `family_name` | Doe | The surname of the end-user. | eHerkenning/eIDAS | | `profile` | `birthdate` | 1986-01-25 | The date of birth of the end-user in the format `YYYY-MM-DD`. | eHerkenning/eIDAS | | `profile` | `gender` | U | The gender of the end-user. Allowed values are: `M` (male), `F` (female), `U` (unknown). | eIDAS | | `phone` | `phone_number`| tel:+31203051900 | The registered phone number of the end-user in the format `tel:+ `. ([ RFC3966](https://tools.ietf.org/html/rfc3966))| eIDAS | | `email` | `email` | jane.doe@example.com | The email address of the end-user. | eHerkenning/eIDAS | | `nationality` | `place_of_birth` | Amsterdam | The place of birth of the end-user (string max 40). | eIDAS | | `nin` | `nin` | 123456789 | The National Identification Number (NIN) associated with the end-user. | eHerkenning/eIDAS | | `eherkenning-extra` | `chamber_of_commerce` | 12345678 | The Chamber of Commerce number (Kamer van Koophandel, KvK) of the organisation. The KvK number consists of 8 digits. | eHerkenning | | `eherkenning-extra` | `eherkenning _intermediate_kvknr` | 87654321 | The Chamber of Commerce (KvK) number of an intermediary company involved in the eHerkenning process. Applies to chain authorisation. | eHerkenning | | `eherkenning-extra` | `eherkenning_vestigingsnr` | 123456789012 | The establishment number or branch number ([Vestigingsnummer](https://www.kvk.nl/en/about-the-business-register/branch-number/) in Dutch) of the organisation. Each branch of a business or legal entity in the Business Register (Handelsregister) has a unique 12-digit branch number. | eHerkenning | | `eherkenning-extra` | `eherkenning_rsin` | 987654321 | The Legal Entities and Partnerships Identification Number ([RSIN](https://www.kvk.nl/en/about-the-business-register/rsin-number/): Rechtspersonen en Samenwerkingsverbanden Informatienummer) associated with the organisation. Consists of 9 digits. | eHerkenning | | `eherkenning-extra` | `eherkenning_probasnr` | PROBAS-00123 | A unique identifier for the organisation in the PROBAS database. The PROBAS number is issued by the Tax Authorities to organisations or persons that are not registered in the Business Register (Handelsregister), such as embassies and consulates. The PROBAS number is registered in the PROBAS register which is managed by the Ministry of Foreign Affairs. | eHerkenning | | `eherkenning-extra` | `eherkenning_trr_bd` | 987654321 | The top-level registration number used in eHerkenning for identifying the individual. | eHerkenning | | `eherkenning-extra` | `eherkenning _intermediate_trr_bd` | 123456789 | An intermediate registration number within the eHerkenning system. | eHerkenning | | `eherkenning-extra` | `eherkenning_pseudo`| See note below \* | The specific pseudonym identifier. | eHerkenning | | `eherkenning-extra` | `eherkenning_pseudo_id`| {/* TODO */} | The PseudoID is used to uniquely identify a natural person. It is a service provider-specific persistent pseudonym that is encrypted specifically per service provider (that is your organisation) for privacy reasons. The PseudoID is always the same for a specific end-user, regardless of the Attesting Party used for authentication. It is hashed and Base64 encoded. | eHerkenning | | `eherkenning-extra` | `eherkenning_service_id` | urn:etoegang:DV:00000000000000000000:services:1010 | An identifier representing a specific service within the eHerkenning framework.| eHerkenning | | `eherkenning-extra` | `eherkenning_service_uuid` | d8f71022-789b-456c-abc1-2f1234567890 | The ServiceUUID is a universally unique identifier (UUID) of a service that is unique in the context of the network, but not linked to one service provider. | eHerkenning | | `eherkenning-extra` | `organisation`| Example BV | The official name of the organisation. | eHerkenning | | `eherkenning-extra` | `eherkenning_intermediate _organisation` | InterExample BV | The name of the organisation acting as an intermediary in eHerkenning. Applies to chain authorisation. Format is string of max length 200. | eHerkenning | | `eherkenning-extra` | `initials` | J | The initials of the end-user's first name(s). | eIDAS | | `eherkenning-extra` | `family_name_infix` | de | The infix or preposition in the user's surname, common in some naming conventions such as `van` or `de`. | eIDAS | | `eherkenning-extra` | `eighteen_or_older` | true | A Boolean attribute indicating whether the end-user is at least 18 years old. Possible values: `true` or `false`. | eIDAS | | `eherkenning-extra` | `sixteen_or_older` | true | A Boolean attribute indicating whether the end-user is at least 16 years old. Possible values: `true` or `false`. | eIDAS | | `eherkenning-extra` | `twelve_or_older` | true | A Boolean attribute indicating whether the end-user is at least 12 years old. Possible values: `true` or `false`. | eIDAS | | `eherkenning-extra` | `sixty_five_or_older` | false| A Boolean attribute indicating whether the end-user is at least 65 years old. Possible values: `true` or `false`. | eIDAS | | `eherkenning-complete` | `organisation_vat _registration_number` | NL123456789B01 | The VAT registration number of the organisation. | eHerkenning | | `eherkenning-complete` | `organisation_tax _reference_number` | 123/ABC/456 | The tax reference number assigned to the organisation. | eHerkenning | | `eherkenning-complete` | `organisation_kvknr` | 87654321 | The registration number of the organisation at the Dutch Chamber of Commerce. | eHerkenning | | `eherkenning-complete` | `organisation_legal _entity_identifier` | 5493001KJTIIGC8Y1R12 | The legal entity identifier (LEI) of the organisation. | eHerkenning | | `eherkenning-complete` | `organisation_eori` | NL123456789012 | The Economic Operators Registration and Identification (EORI) number of the organisation. | eHerkenning | | `eherkenning-complete` | `organisation_seed` | 12345ABCD6789EFGH | The Single European Electronic Data (SEED) number for the organisation. | eHerkenning | | `eherkenning-complete` | `organisation_sic` | 62020 | The [Standard Industrial Classification (SIC)](https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list) code representing the industry of the organisation. | eHerkenning/eIDAS | | `eherkenning-complete` | `organisation_postal_code` | 1012WX | The postal code for the organisation's address. | eHerkenning | | `eherkenning-complete` | `organisation_house_number` | 123 | The house number of the organisation's registered address. | eHerkenning | | `eherkenning-complete` | `organisation_house _number_suffix` | A | The suffix of the house number, if applicable. | eHerkenning | | `eherkenning-complete` | `organisation_po_box` | 5678 | The PO box number of the organisation, if applicable. | eHerkenning | | `eherkenning-complete` | `organisation_street_name` | Main Street | The street name of the organisation's registered address. | eHerkenning | | `eherkenning-complete` | `organisation_locator _designator` | Unit 3 | An additional designator to locate the address, such as "Unit" or "Suite". | eHerkenning | | `eherkenning-complete` | `organisation_locator_name` | Innovation Centre | The name of a building or facility at the organisation's address. | eHerkenning | | `eherkenning-complete` | `organisation_address_area` | Midtown | A sub-area or neighbourhood within the organisation's city. | eHerkenning | | `eherkenning-complete` | `organisation_city` | Amsterdam | The city where the organisation is located. | eHerkenning | | `eherkenning-complete` | `organisation_region` | North Holland | The region or province where the organisation is located. | eHerkenning | | `eherkenning-complete` | `organisation_country_code` | NL | The two-letter ISO country code of the organisation's location. | eHerkenning | | `eherkenning-complete` | `birth_name` | Jane Marie Doe | The full birth name of the individual. | eIDAS | | `eherkenning-complete` | `eherkenning_first_name _non_transliterated` | Ян | The first name of the individual in its original script (non-transliterated). | eIDAS | | `eherkenning-complete` | `eherkenning_last_name _non_transliterated` | Иванов | The last name of the individual in its original script (non-transliterated). | eIDAS | | `eherkenning-complete` | `eherkenning_first_name _at_birth` | Jan | The first name of the individual at birth. | eIDAS | | `eherkenning-complete` | `eherkenning_last_name _at_birth` | Jansen | The last name of the individual at birth. | eIDAS | ::: \* **Pseudonym example:** `ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890` ## Examples When connecting with OIDC, you specify the scopes in the authorisation request. After the end-user verifies their identity, consents to sharing their data and the flow is complete, you can retrieve the claims in the ID Token or through the UserInfo endpoint. Below, you find examples of requests and responses to gain insight into the exchange of user information that occurs during an authentication process with OIDC. ### Request example To trigger an authentication, you build an OIDC request like: ```http https:///auth/open/connect/authorize? &client_id= &response_type=code &redirect_uri= &state=1599045135410-jFe &scope=openid%20profile%20idp-id%20email%20phone%20nin%20nationality%20eherkenning-extra &acr_values=idp:eherkenning &prompt=login &nonce=1599046102647-dv4 ``` Note the following request parameters shown in the example above: - `scope`: The scope specifies the set of claims that the client application is requesting from eHerkenning. - `acr_values`: The Authentication Context Class Reference (ACR) values determine the type or level of authentication required. The example above is requesting to use only eHerkenning as Identity Provider (IdP) for authentication. ### Response example Below, you find an example of a response obtained from an identity verification flow with eHerkenning. Scopes in request: `openid`, `profile`, `idp-id`, `email`, `phone`, `nationality`, `nin`, `eherkenning-extra` Example of **ID token** in response: ```json { "iss":"https:///auth/open", "nbf":1726046529, "iat":1726046529, "exp":1726047129, "aud":"", "amr":[ "external" ], "at_hash":"_T539pqKJTOovx1xVyMnKA", "sid":"783EFB56CEE40C1FA95F0543535B6E4E", "sub":"X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=", "auth_time":1726046523, "idp":"eherkenning", "idp_id":"E0DA125456E34014919EC26C5B1E6D9A8A5F7F2663A14C4D98BB6ADB3426FF09","serviceID":"urn:etoegang:DV::services:1010","serviceUUID":"47b842fd-0d0e-4385-88a4-06eb462fdf3b","idp_issuer":"urn:etoegang:HM::entities:9713","transaction_id":"1bb891ff-4420-fb4b-99f5-bdf2817a7725", "sandbox":true } ``` :::tip ID Token The ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, edit the **ID Token User data** field in the **Advanced > Security** tab of your OIDC client configuration in the [Signicat Dashboard](https://dashboard.signicat.com/oidc-clients/). ::: Example of a response from the **UserInfo** endpoint: ```json { "sub": "1234567890", "idp_issuer": "urn:etoegang:HM::entities:9713", "idp_id": "ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890", "given_name": "Jane", "initials": "J.", "family_name": "Doe", "family_name_infix": "van", "birthdate": "1980-01-15", "gender": "F", "phone_number": "tel:+31612345678", "email": "jane.doe@example.com", "place_of_birth": "Amsterdam", "nin": "123456789", "nin_type": "BSN", "nin_issuing_country": "NL", "eighteen_or_older": true, "sixteen_or_older": true, "twelve_or_older": true, "sixty_five_or_older": false, "chamber_of_commerce": "12345678", "eherkenning_intermediate_kvknr": "87654321", "eherkenning_vestigingsnr": "123400567890", "eherkenning_rsin": "987654321", "eherkenning_probasnr": "PROBAS-00123", "eherkenning_pseudo": "pseudo-org-12345", "eherkenning_pseudo_id": "pseudo-id-67890", "eherkenning_service_id": "urn:etoegang:DV::services:1010", "eherkenning_service_uuid": "d8f71022-789b-456c-abc1-2f1234567890", "organisation": "Example BV", "eherkenning_intermediate_organisation": "Intermediate Services BV" } ``` --- ## eHerkenning attributes in SAML 2.0 This page contains information about the user attributes that you can request and retrieve from eHerkenning when using [SAML 2.0](/docs/eid-hub/saml-2-0/) as an authentication protocol. :::tip Attribute glossary To learn more about the properties of the data available through eHerkenning, visit the [Attribute glossary](/identity-methods/eherkenning/attributes-reference/glossary/) page. ::: ## Attributes table eHerkenning provides the following data: :::CustomTable | Attribute | Example | Description | Source | |:----------------|:-------------------|:---------------------------|:------------| | `idpId` | See note below \* | The raw (unhashed) value of the subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions.| eHerkenning | | `firstName` | Jane | The first name(s) of the end-user. | eHerkenning/eIDAS | | `lastName` | Doe | The surname of the end-user. | eHerkenning/eIDAS | | `dateOfBirth` | 1986-01-25 | The date of birth of the end-user in the format `YYYY-MM-DD`. | eHerkenning/eIDAS | | `gender` | U | The gender of the end-user. Allowed values are: `M` (male), `F` (female), `U` (unknown).| eIDAS | | `phoneNumber` | tel:+31203051900 | The registered phone number of the end-user in the format `tel:+ `. ([RFC3966](https://tools.ietf.org/html/rfc3966)) | eIDAS | | `email` | jane.doe@example.com | The email address of the end-user. | eHerkenning/eIDAS | | `placeOfBirth` | Amsterdam | The place of birth of the end-user (string max 40). | eIDAS | | `nin` | 123456789 | The National Identification Number (NIN) associated with the end-user. | eHerkenning/eIDAS | | `chamberOfCommerce` | 12345678 | The Chamber of Commerce number (Kamer van Koophandel, KvK) of the organisation. The KvK number consists of 8 digits. | eHerkenning | | `eherkenningIntermediatekvkNr` | 87654321 | The Chamber of Commerce (KvK) number of an intermediary company involved in the eHerkenning process. Applies to chain authorisation. | eHerkenning | | `eherkenningVestigingsNr`| 123456789012 | The establishment number or branch number ([Vestigingsnummer](https://www.kvk.nl/en/about-the-business-register/branch-number/) in Dutch) of the organisation. Each branch of a business or legal entity in the Business Register (Handelsregister) has a unique 12-digit branch number. | eHerkenning | | `eherkenningRsin` | 987654321 | The Legal Entities and Partnerships Identification Number ([RSIN](https://www.kvk.nl/en/about-the-business-register/rsin-number/): Rechtspersonen en Samenwerkingsverbanden Informatienummer) associated with the organisation. Consists of 9 digits. | eHerkenning | | `eherkenningProbasNr` | PROBAS-00123 | A unique identifier for the organisation in the PROBAS database. The PROBAS number is issued by the Tax Authorities to organisations or persons that are not registered in the Business Register (Handelsregister), such as embassies and consulates. The PROBAS number is registered in the PROBAS register which is managed by the Ministry of Foreign Affairs. | eHerkenning | | `eherkenningTrrBd` | 987654321 | The top-level registration number used in eHerkenning for identifying the individual. | eHerkenning | | `eherkenningIntermediateTrrBd` | 123456789 | An intermediate registration number within the eHerkenning system. | eHerkenning | | `eherkenningPseudo`| See note below \* | The specific pseudonym identifier. | eHerkenning | | `eherkenningPseudoID` | | The PseudoID is used to uniquely identify a natural person. It is a service provider-specific persistent pseudonym that is encrypted specifically per service provider (that is your organisation) for privacy reasons. The PseudoID is always the same for a specific end-user, regardless of the Attesting Party used for authentication. It is hashed and Base64 encoded. | eHerkenning | | `eherkenningServiceID`| urn:etoegang:DV:00000000000000000000:services:1010 | An identifier representing a specific service within the eHerkenning framework.| eHerkenning | | `eherkenningServiceUUID` | d8f71022-789b-456c-abc1-2f1234567890 | The ServiceUUID is a universally unique identifier (UUID) of a service that is unique in the context of the network, but not linked to one service provider. | eHerkenning | | `organisationName` | Example BV | The official name of the organisation. | eHerkenning | | `eherkenningIntermediate OrganisationName` | InterExample BV | The name of the organisation acting as an intermediary in eHerkenning. Applies to chain authorisation. Format is string of max length 200. | eHerkenning | | `initials` | J | The initials of the end-user's first name(s). | eIDAS | | `familyNameInfix` | de| The infix or preposition in the user's surname, common in some naming conventions such as `van` or `de`. | eIDAS | | `18OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 18 years old. Possible values: `true` or `false`. | eIDAS | | `16OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 16 years old. Possible values: `true` or `false`. | eIDAS | | `12OrOlder` | true | A Boolean attribute indicating whether the end-user is at least 12 years old. Possible values: `true` or `false`. | eIDAS | | `65OrOlder` | false| A Boolean attribute indicating whether the end-user is at least 65 years old. Possible values: `true` or `false`. | eIDAS | | `organisationVatRegistrationNumber` | NL123456789B01 | The VAT registration number of the organisation. | eHerkenning | | `organisationTaxReferenceNumber` | 123/ABC/456 | The tax reference number assigned to the organisation. | eHerkenning | | `organisationKvkNr` | 87654321 | The registration number of the organisation at the Dutch Chamber of Commerce. | eHerkenning | | `organisationLegalEntityIdentifier` | 5493001KJTIIGC8Y1R12 | The legal entity identifier (LEI) of the organisation. | eHerkenning | | `organisationEori` | NL123456789012 | The Economic Operators Registration and Identification (EORI) number of the organisation. | eHerkenning | | `organisationSeed` | 12345ABCD6789EFGH | The Single European Electronic Data (SEED) number for the organisation. | eHerkenning | | `organisationSic` | 62020 | The [Standard Industrial Classification (SIC)](https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list) code representing the industry of the organisation. | eHerkenning | | `organisationPostalCode` | 1012WX | The postal code for the organisation's address. | eHerkenning | | `organisationHouseNumber` | 123 | The house number of the organisation's registered address. | eHerkenning | | `organisationHouseNumberSuffix` | A | The suffix of the house number, if applicable. | eHerkenning | | `organisationPoBox` | 5678 | The postal office box number of the organisation, if applicable. | eHerkenning | | `organisationStreetName` | Main Street | The street name of the organisation's registered address. | eHerkenning | | `organisationLocatorDesignator` | Unit 3 | An additional designator to locate the address, such as "Unit" or "Suite". | eHerkenning | | `organisationLocatorName` | Innovation Centre | The name of a building or facility at the organisation's address. | eHerkenning | | `organisationAddressArea` | Midtown | A sub-area or neighbourhood within the organisation's city. | eHerkenning | | `organisationCity` | Amsterdam | The city where the organisation is located. | eHerkenning | | `organisationRegion` | North Holland | The region or province where the organisation is located. | eHerkenning | | `organisationCountryCode` | NL | The two-letter ISO country code of the organisation's location. | eHerkenning | | `birthName` | Jane Marie Doe | The full birth name of the individual. | eHerkenning | | `eherkenningFirstName NonTransliterated` | Ян | The first name of the individual in its original script (non-transliterated). | eHerkenning | | `eherkenningLastName NonTransliterated` | Иванов | The last name of the individual in its original script (non-transliterated). | eHerkenning | | `eherkenningFirstNameAtBirth` | Jan | The first name of the individual at birth. | eHerkenning | | `eherkenningLastNameAtBirth` | Jansen | The last name of the individual at birth. | eHerkenning | ::: \* **Pseudonym example:** `ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890` ## Examples ### Metadata document The example below shows a Service Provider (SP) metadata document to connect to eHerkenning and request the attributes: `idpId`, `firstName`, `lastName`, `dateOfBirth`, `gender`, `phoneNumber`, `email`, `placeOfBirth`, `nin`, `chamberOfCommerce`, `eherkenningIntermediatekvkNr`, `eherkenningVestigingsNr`, `eherkenningRsin`, `eherkenningProbasNr`, `eherkenningPseudo`, `eherkenningPseudoID`, `eherkenningServiceID`, `eherkenningServiceUUID`, `organisationName`, `eherkenningIntermediateOrganisationName`, `initials`, `familyNameInfix`, `18OrOlder`, `16OrOlder`, `12OrOlder`, `65OrOlder` ```xml X509_CERTIFICATE All attributes ``` ### Request example SAML 2.0 request example: ```xml urn:etoegang:DV:ORGANISATION_IDENTIFICATION_NUMBER:entities:SERVICE_INDEX urn:etoegang:core:assurance-class:LOA ``` ### Response example SAML 2.0 response example: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml 6SzxrEyAEB6ISrgbZCuI479WvmLh9sEH4OoOHEZB3n8= XML_SIGNATURE X509_CERTIFICATE https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ihgBWyK1tVczI5T7RJCOrMB92/ArGNGN8D9C0NQJ6a0= XML_SIGNATURE X509_CERTIFICATE gjhtHxMFfm-2bn-YaZ6mh2YfTL62z-EyU2AdnWbx3x4= ENTITY_ID eh-idp-01 Jane J. Doe van 1980-01-15 male +31612345678 jane.doe@example.com Amsterdam 123456789 true 12345678 87654321 123400567890 987654321 PROBAS-00123 pseudo-org-12345 pseudo-id-67890 service-001 d8f71022-789b-456c-abc1-2f1234567890 Example BV Intermediate Services BV urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:etoegang:HM:ORGANISATION_IDENTIFICATION_NUMBER:entities:9713 ``` --- ## Attribute glossary eHerkenning gets you access to several numbers to identify different types of business entities. This page aims to provide additional information about the characteristics of these numbers. ## idpId The raw (unhashed) value of the subject ID. We return the first existing (not-null) value of the following attributes with the following order: 1. Specific pseudonym (see [Pseudo](#pseudo) attribute) 2. Encrypted BSN (eIDAS) 3. [Encrypted pseudonym](https://afsprakenstelsel.etoegang.nl/Startpagina/as/encrypted-pseudonym) (eIDAS) 4. Pseudonym (eIDAS) {/* todo: what Pseudonym is #4? PSEUDONYM_19 */} Note that to receive the raw value of the subject (`idpId`), you must request it in your authentication request using the `idpId` (`idp-id` for OIDC) parameter. To learn more, see the [attributes reference](/identity-methods/eherkenning/attributes-reference/index.mdx) documentation. ## KvK number The [Chamber of Commerce (KvK)](https://www.kvk.nl/) number of the organisation. Every new company in the Netherlands must register in the Business Register (Handelsregister) of the Netherlands Chamber of Commerce KVK. When a company registers, they receive a KvK number that serves as a proof that they are a registered business. You can search for companies in the Business Register at [https://www.kvk.nl/zoeken/](https://www.kvk.nl/zoeken/). The KvK number consists of 8 digits, for example 12345678. ## EORI The Economic Operators Registration and Identification number (EORI number) is a registration and identification number for businesses that trade goods into and out of the European Union (EU). The number applies to organisations that are based in the EU and undertake customs activities in the EU. ## LEI The Legal Entity Identifier (LEI) is a unique number that the Dutch Financial Authority AFM uses to trace global transactions. Companies that are legal entities (for instance private or public limited companies) are required to have a LEI if: - They trade shares (including their own) or derivatives on the stock exchange. - They are a foreign legal entity, but registered in the Dutch Business Register (Handelsregister) and trading on the stock exchange. ## PROBAS The PROBAS number is issued by the Tax Authorities to organisations/persons that are not registered in the Business Register (Handelsregister), such as embassies and consulates. The PROBAS number is registered in the PROBAS register which is managed by the Ministry of Foreign Affairs. ## Pseudo The [Specific pseudonym](https://afsprakenstelsel.etoegang.nl/Startpagina/as/specific-pseudonym) is a unique identifier for each different combination of user, represented service consumer, intermediary and service provider. The format is a 32 bytes integer in hexadecimal format (which contains information about the user) followed by the `@` sign and a 16 bytes integer in hexadecimal format (represented with 32 digits) such that `64digitsHex@32digitsHex`. For example: `ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234567890ABCDEF1234567890` ## Pseudo ID The PseudoID is a service provider-specific [persistent pseudonym](https://afsprakenstelsel.etoegang.nl/Startpagina/as/persistent-pseudonym) that is encrypted specifically per service provider (your organisation) for privacy reasons. The PseudoID is identical for the end-user, regardless of the eHerkenning provider used for authentication. It is hashed and Base64 encoded. ## RSIN The Legal Entities and Partnerships Identification Number ([RSIN](https://www.kvk.nl/en/about-the-business-register/rsin-number/) stands for Rechtspersonen en Samenwerkingsverbanden Informatienummer in Dutch) is a unique identification number for legal entities and partnerships. Sole proprietorship (self-employed) organisations do not have an RSIN. It is intended for (government) organisations to easily exchange information with each other. The number consists of 9 digits. ## SEED The Single European Electronic Data (SEED) number is a unique identifier assigned to authorised operators and warehouses within the EU to facilitate the movement of excisable goods, such as alcohol, tobacco, and energy products, between member states. It is stored in the Single European Electronic Data (SEED) system, which allows authorities to verify the status of traders and prevent fraud. ## Service ID When you register a new service in the service catalogue, the service is assigned: - Service ID - Service UUID The **Service ID** is string to uniquely identify a service in the context of your organisation. It is an URN with the following format: `urn:etoegang:DV::services:` where: - `ORGANISATION_IDENTIFICATION_NUMBER` is your Organization Identifying Number (OIN). - `SERVICE_INDEX` is the number you provided when creating the service in the Signicat Dashboard. For example: `urn:etoegang:DV:0000000X123456780000:services:1010` ## Service UUID The ServiceUUID is an identifier of a service that is unique in the context of the eHerkenning network. ## SIC The [Standard Industrial Classification (SIC)](https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list) is a four-digit code to classify the type of business of an organisation. It is used for statistical purposes across agencies. ## Subject ID The Subject ID identifies the end-user that performed the authentication transaction. After an authentication transaction, you always receive the subject in hashed form in the response. In the case of eHerkenning, Signicat returns the hashed value of the [idpId](#idpid) (raw subject) as subject in the response. :::CustomTable{columnWidths="33% 33% 33%"} | Protocol | Hashed subject | Raw subject | |:-------------------------------- |:-------------- |:------------| | OpenID Connect (OIDC) | `sub` | `idp-id` | | Signicat Authentication REST API | `subject.id` | `idpId` | | SAML 2.0 | `NameID` | `idpId` | ::: Read more about the [subject](/docs/eid-hub/concepts/subject.mdx). ## Vestigingsnummer Branch number ([Vestigingsnummer](https://www.kvk.nl/en/about-the-business-register/branch-number/) in Dutch). Any legal entity that has a branch must officially register this branch. Each branch of a business or legal entity in the Business Register (Handelsregister) has a unique 12-digit branch number. For example, 321654871234. ## Additional resources - [Dutch business numbers](https://business.gov.nl/starting-your-business/registering-your-business/lei-rsin-vat-and-kvk-number-which-is-which/) - [eHerkenning Agreement System](https://afsprakenstelsel.etoegang.nl/) --- ## Attributes reference(3) When you integrate eHerkenning to verify the identity of users accessing your online services, you request and obtain personal information relevant to your use case. To discover what kind of information is available for a given authentication protocol, visit the respective pages listed below: - [eHerkenning attributes in OpenID Connect (OIDC)](/identity-methods/eherkenning/attributes-reference/eherkenning-attributes-oidc.mdx) - [eHerkenning attributes in SAML 2.0](/identity-methods/eherkenning/attributes-reference/eherkenning-attributes-saml.mdx) - [eHerkenning attributes in the Signicat Authentication REST API](/identity-methods/eherkenning/attributes-reference/eherkenning-attributes-authentication-api.mdx) In the pages above you'll also find examples of requests and responses to understand the properties of the data you receive. For high-level information about the data points, see the [Attribute glossary](/identity-methods/eherkenning/attributes-reference/glossary.mdx). ## How to request attributes :::warning How to request attributes To request user attributes with eHerkenning, you *must* specify the attributes in both: - The service configuration. You do this in the Dashboard. - The authorisation request. This is the request your application sends to trigger an authentication process. ::: To specify and request attributes from eHerkenning, do the following: 1. Add the attributes in the service configuration in the service catalogue. 2. Specify what attributes from step 1 you want to receive in the authentication request. :::note Note In the authentication request you can only specify attributes from the list of attributes that you previously added in the service configuration. In the response, you only receive data corresponding to the attributes that you specify in the authentication request. ::: ## Available attributes User attributes allow you to specify the type of data that you wish to obtain from end-user authentication. The data your application can request depend on the information required by your use case and your agreement with Signicat. Additionally, the attributes you can request depend on the configuration of your service in the service catalogue. Here is an overview of the attributes you can request. **Identifying attributes - eHerkenning** - Pseudonym - KvK Number (chamber of commerce) - RSIN - BSN (in case of sole proprietors) - Organisation legal name - Name - More optional additional attributes **Identifying attributes - eIDAS (legal persons)** - Organisation legal name - BSN (citizen service number) - PseudoID - VAT - TAX number - LEI **Identifying attributes - eIDAS (naturals persons)** - BSN - PseudoID - Family name - First name - Date of birth - Place of birth - Address - Gender After the end-user consents to share the requested attributes and completes an authentication transaction, you can retrieve the data from an endpoint - this step depends on the authentication protocol you integrate with. ## Additional resources For more information about the user attributes, consult the official [eHerkenning Attribuutcatalogus](https://afsprakenstelsel.etoegang.nl/Startpagina/as/attribuutcatalogus). --- ## Communication guide Once you have set up a connection to eHerkenning, it is important to tell your customers about the new setup, the way they log in is changing and that they will need to have an eHerkenning login. ## eHerkenning communication The eHerkenning Communication Guide provides step-by-step advice on communicating information to the relevant people. For more information, read the "Handleiding Communicatie" (Communication Guide) in the [eHerkenning - Handbooks and support](https://www.eherkenning.nl/en/voor-dienstverleners/aansluiten/handbooks-and-support) page. The eHerkenning logo, login buttons and assurance levels can be downloaded [here](pathname:///uploaded-media/id-methods/eherkenning/eherkenning-communication-toolkit.zip). ## eIDAS communication The information below is taken from the [Logius eIDAS Communication Manual](https://logius.nl/diensten/eidas/eidas-documentatie/handleiding-communicatietools-eIDAS). #### Communication checklist: setting up your website for eIDAS When setting up your website for eIDAS, consider the following: 1. **Texts**: provide a clear explanation about eIDAS on your website. Use text elements and visual elements, such as the logo. 2. **Images**: use the EU flag as a visual marker for European login, at the login button for European login. As a result, European citizens and companies know that they can log in to your service using this button. #### Text elements eIDAS Your organisation must be able to grant holders of eIDAS-recognised eIDs access to your digital services. This means that a multitude of European users can access your services. The eIDAS regulation does not oblige organisations to translate the service into multiple European languages. However, your organisation can use a number of standard text elements in English. #### Word of welcome Make it clear to European users that they can log in with their European eIDs. If you want to indicate that the service is only for citizens or companies, you can add '(for businesses)' or '(for citizens)'. You can use the following options: 1. Here you can log in with a European-recognised login means. 2. Do you have a European approved digital identity? Please login here. 3. Log in with your European digital identity. #### Key messages If you want to provide European users with more information about the possibilities of eIDAS, you can use an in-depth text. Keep in mind that the term eIDAS is often still unknown to a European user. #### Take your European digital identity with you, everywhere you go in Europe Are you in the possession of an eIDAS-approved digital identity? That means that you can take advantage of the eIDAS-regulation that becomes effective on the 29th of September 2018. Accessing online public services like filing your income taxes at the Dutch Tax Authority or registering for courses at a Dutch university are made accessible to you without physically having to cross the border. This applies to all online public services that are already available to local citizens in possession of a digital identity, in all of the European Union. #### EU flag and files application The EU flag is available in various formats to use on your website as a visual marker at the login button for European login. You can find these files in the communication toolkit. Requirements: - The EU flag itself should not be used as a login button. - In the communication toolkit, you can find application examples of how to use the EU flag next to the login button. The logo is also well scalable. In the communication toolkit you can find both logos in different sizes (150, 300, 500 px) and formats (CMYK and RGB, PNG, EPS, AI). To receive the toolkit, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. --- ## Frequently Asked Questions Find quick answers to common questions about eHerkenning. ## Setting up an eHerkenning connection Find out more about setting up an eHerkenning connection. #### What is a connection? A connection is a network connection between your app (web application or mobile) and the Signicat eID and Wallet Hub. The methods of communication are defined by the authentication protocol. #### What authentication protocols does Signicat offer? With Signicat you can integrate using the following authentication protocols: - [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) - [Security Assertion Markup Language (SAML) 2.0](/docs/eid-hub/saml-2-0/) - [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) To learn more about the protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. #### What is needed to connect to eHerkenning with Signicat? To connect to the Signicat eID and Wallet Hub, you must provide us with: - A signed contract - A signed [eHerkenning self-declaration](https://afsprakenstelsel.etoegang.nl/Startpagina/as/template-zelfverklaring-dienstverlener) - PKIoverheid certificate (type Private Services CA G1) - Organisation identification number (OIN) Additionally, you should consider the following items: - Register on the [authorisation list for BSN (ALB)](https://www.rvig.nl/autorisatielijst-bsn-gerechtigden), if you want to request the BSN of users. - Determine the appropriate Level of Assurance (LoA) for the service by following the guidelines at [https://www.forumstandaardisatie.nl/onderwerpen/veilig-internet/betrouwbaarheidsniveaus](https://www.forumstandaardisatie.nl/onderwerpen/veilig-internet/betrouwbaarheidsniveaus). - Determine which identifying attributes and optional attributes you want to request from your users. - Note that you must include a purpose of use statement for each optional attribute requested from your users. You add this in the eHerkenning service catalogue. - Provide a link to your up-to-date privacy policy. You add this in the eHerkenning service catalogue. - Choose service name(s) and branding in line with eHerkenning and eIDAS guidelines. #### What is an OIN? This is an Organisation Identification Number or also called a Government Identification Number. You use it to identify yourself as an organisation. ## eHerkenning/eIDAS This section addresses queries about eHerkenning and the eIDAS network. #### If I connect eHerkenning, does eIDAS come standard? This is not standard, but depends on the contract you enter into with Signicat. eHerkenning and eIDAS are different products that use the same technical network. However, both eHerkenning and eIDAS can be accessed through the same connection. Please contact sales to find out more. #### Is it necessary for eIDAS to set up a separate connection next to eHerkenning? No, this is not necessary. eHerkenning and eIDAS can be accessed through the same connection. Therefore, there is no need to set up a separate connection for the different channels. However, to make a service an eIDAS service, the [eIDAS classifiers](/identity-methods/eherkenning/integration/service-catalogue.mdx) need to be added to the service in the catalogue. Some applications cannot handle serving multiple eIDs over a single connection. In that case, we recommend setting up two separate connections. ## Certificates Certificates help you secure connections between your app and eHerkenning and can be used to encrypt data and sign messages. #### What is a PKIoverheid certificate? PKI stands for *Public Key Infrastructure*, a digital certificate that allows you to exchange data securely online with government agencies and the Tax and Customs Administration among others. PKI is an international standard when it comes to signing data and messages. You can therefore obtain a PKI certificate in various ways, however, this is not sufficient for interactions with the Dutch government. The Dutch government states that you need a *PKIoverheid (PKIo)* certificate. A PKIoverheid certificate is a regular PKI certificate, but issued by a Certificate Authority (CA) that has been authorised by the government. They must meet strict requirements of the government. You can learn more about PKIo certificates at [https://cert.pkioverheid.nl/](https://cert.pkioverheid.nl/). #### Will you be informed when a certificate is about to expire? On a best effort basis, Signicat tries to inform you when a certificate is about to expire. However, the ultimate responsibility rests with you. So, make sure that your organisation provides new certificates to Signicat's technical support department in a timely manner. #### You provide services for a government agency. Can you apply for a PKIoverheid certificate yourself? Yes, you can. More information can be found at [https://www.pkioverheid.nl](https://www.pkioverheid.nl). ## Services Services are an essential concept in eHerkenning. Learn more about services below. #### Service names in the service catalogue With eHerkenning, you specify services by entering them in the service catalogue. It is important to use clear names. View the official manual "Handleiding Dienstencatalogus" containing the obligations and advice on filling in the required fields in the [eHerkenning - Handbooks and support](https://www.eherkenning.nl/en/voor-dienstverleners/aansluiten/handbooks-and-support) page. :::warning Naming a service The name of the service is very important. The name should be meaningful and distinguishable. For example, the names 'Department 1' & 'Department Municipality X' may not be clear enough for the user. Another reason is that a proper name helps users and organisations with choosing the right permissions on their eHerkenning login. Note that the user should immediately know what to do based on the name of the service. For example, if you create a service to apply for a subsidy, call the service 'Apply for a subsidy'. ::: #### Changing a service UUID Every service in the eHerkenning service catalogue has a UUID. This is a unique number that is characteristic for a certain service. Permissions that are linked to the eHerkenning the user's resources are issued based on UUIDs. When you add a new service, the service is assigned a UUID. In the case of minor changes, the UUID must always remain the same. However, you must change the service UUID if one of the following changes occurs: - Changing the level of assurance (LoA). - Changing the purpose and scope of the service. - Changing significantly the personal user data you request. This may impact the LoA. - Moving services under a portal service. - Changing the legal entity and OIN of you organisation. When a service changes its UUID, the users must re-link the new service to their eHerkenning device in order to gain access. Therefore, it is important that the UUID remains the same in the event of minor changes, otherwise users will no longer be able to log in with mandated permissions and will have to link another service to their eHerkenning device. For more FAQs about eHerkenning permissions, visit [https://we-id.nl/en/](https://we-id.nl/en/) and [https://www.eherkenning.nl/nl/machtigen](https://www.eherkenning.nl/nl/machtigen). ## Support This section outlines ways for you to get the assistance you need with eHerkenning. #### Is there a health check available? Yes, you can ping our infrastructure at `https:///broker/.ping`. Change the `` in the URL to the domain name associated with your account in the **Settings** > [**Domains**](https://dashboard.signicat.com/domains) page in the Dashboard. You can also monitor the status of Signicat services in our [Status page](https://status.signicat.com/). #### Where can I find outage and maintenance reports? You can monitor system-wide outages on the reporting page of [eHerkenning: Outage and Maintenance](https://www.eherkenning.nl/nl/contact/onderhoud-en-storingen). --- Is your question not listed? You can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## eHerkenning eHerkenning supports business identification of end-users towards public and private organisations in the Netherlands and is notified for European login under eIDAS. With eHerkenning, you: - Allow users to log in to your public or private services on behalf of their organisations through registered authorisations. - Allow organisations to represent themselves by intermediaries based on registered authorisations. - Allow users of other European eIDs to log in to your digital services through the eIDAS network. Signicat is a certified eHerkenning broker (makelaar in Dutch), compliant with the Dutch Trust Framework for Electronic Identification (Afsprakenstelsel Elektronische Toegangsdiensten in Dutch). If you want to read more about eHerkenning before you start the integration, see [About eHerkenning](/identity-methods/eherkenning/about-eherkenning.mdx). :::note Facts about eHerkenning - Countries: The Netherlands. - Use cases: Business identification and authorization, Authentication (with eIDAS). - Supported protocols: OIDC, Authentication REST API, SAML 2.0. - Devices: Mobile, desktop. - [Key attributes](/identity-methods/eherkenning/attributes-reference/): - eHerkenning: Pseudonym, KvK Number, organisation legal name and more. - eIDAS: Name, BSN, PseudoID, date of birth and more. - LoA: Low, Substantial and High. ::: ## Get started * [**Integration guides**](/identity-methods/eherkenning/integration/): Learn how to set up, configure and test the integration * [**Attributes reference**](/identity-methods/eherkenning/attributes-reference/): Data, request and response examples per protocol ## Tell me more * [**About eHerkenning**](/identity-methods/eherkenning/about-eherkenning): High-level information about eHerkenning * [**Communication guide**](/identity-methods/eherkenning/communication): Get advice on how to communicate information about eHerkenning/eIDAS to your users * [**Frequently asked questions**](/identity-methods/eherkenning/frequently-asked-questions): Questions and answers on how to connect with eHerkenning ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Connect with an authentication protocol When an end-user wants to authenticate with your services using eHerkenning, your application sends/receives a series of requests/responses to/from Signicat eID and Wallet Hub, which acts as message broker between your application and the eHerkenning network. To manage the communication between your application and the Signicat eID and Wallet Hub, you connect using an authentication protocol. ## Prerequisites This guide assumes you have completed the steps in the following guides: 1. [Initial preparations](/identity-methods/eherkenning/integration/initial-preparations.mdx). 2. [Manage certificates](/identity-methods/eherkenning/integration/manage-certificates.mdx). 3. [Add eHerkenning in the Dashboard](/identity-methods/eherkenning/integration/setup-dashboard.mdx). 4. [Set up a service in the service catalogue](/identity-methods/eherkenning/integration/service-catalogue.mdx). ## Set up a connection With Signicat you can integrate using the following authentication protocols: - [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) - [Security Assertion Markup Language (SAML) 2.0](/docs/eid-hub/saml-2-0/) - [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) :::info Picking a protocol OIDC and SAML 2.0 are official identity protocols. We recommend using OIDC since implementing SAML 2.0 involves more advanced steps. The [Authentication REST API](/apis/eid-hub/) - developed and maintained by Signicat - offers more flexibility and supports _headless_ and _redirect_ integration flow(s) (grant type). You can find integration guides and more information about each protocol in the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: :::info Want to learn more? For general information about integrating with Signicat, see the **eID and Wallet Hub** [Quick start guide](/docs/eid-hub/quick-start/). ::: ## Authentication requests The authentication protocol you integrate with determines how you build an authentication request and the format of the parameters you use. With eHerkenning, you can also configure provider-specific aspects like scoping the eID and the service. This allows you to skip selection screens and route the user directly to the service you intend to use for authentication. ### Scoping eHerkenning services When starting an authentication session, you can specify a service that you defined in your [eHerkenning service catalogue](/identity-methods/eherkenning/integration/service-catalogue/). This allows you to target one service in particular by using its index value. As a result, the end-users are automatically routed to the service you pass in your authentication request thus skipping any service selection screen. When sending an authentication request with OIDC, the `acr_values` attribute allows you to provide additional parameters. To pass the eHerkenning service index, you need to provide the index with the `service_index:SERVICE_INDEX` parameter in the ACR Values. For example, to route to the **Service Index 9701**, you need to pass *9701* as the value for the `service_index` property, as shown below: ```curl {9} title="OIDC Authentication request with service index" https://example.sandbox.signicat.com/auth/open/connect/authorize? client_id=sandbox-vivid-blade-759 &response_type=code &redirect_uri=https://oauth.tools/callback/code &state=1734687023840-WGZ &scope=openid%20profile%20nin &code_challenge=7aEnwazbpKXHjOYbISsHWbtAWn33fE9cgDpS0y4-0UM &code_challenge_method=S256 &acr_values=idp:eherkenning%20service_index:9701 ``` Note that `idp:eherkenning` allows you to specify eHerkenning as the eID where to direct your end-users therefore skipping the eID provider screen. To route end-users directly to an eHerkenning service, you need to pass `signicat:param:service_index` in the `RequestedAttribute` in your SAML 2.0 request and specify the issuer code in the `AttributeValue` object. For example, to route to the **Service Index 9701**, you need to pass *9701* as the value in the `AttributeValue`, as shown below: ```xml {24,27} ENTITY_ID 9701 ``` Note that the `Scoping` object allows you to specify eHerkenning as the eID where to direct your end-users therefore skipping the eID provider screen. To route end-users directly to an eHerkenning service, you need to define the service index in the `allowedProviders` in the body of the [CreateSession](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, to route to the **Service Index 9701**, you need to pass *9701* as the value for the `service_index` field, as shown below: ```json { "allowedProviders": ["eherkenning"], "additionalParameters": { "service_index" : "9701" }, ... } ``` Note that `allowedProviders` allows you to specify eHerkenning as the eID where to direct your end-users therefore skipping the eID provider screen. ## Data and attributes To view the attributes supported by each authentication protocol and examples of requests and responses, see the [Attributes reference](/identity-methods/eherkenning/attributes-reference/) page. ## Communicating changes Once you have an eHerkenning connection, it is important to tell your customers about the new setup. For more information, see the [Communication guide](/identity-methods/eherkenning/communication.mdx). --- ## Overview To establish a connection with eHerkenning through Signicat, you need to complete the following steps: 1. Sign up with Signicat and sign agreements. 2. Obtain PKIoverheid certificates. 3. Configure eHerkenning in the Signicat Dashboard. 4. Set up the service catalogue. 5. Connect to eHerkenning with an authentication protocol. You can find instructions for each of these steps in the guides below. :::warning Pre-production and production It is important to note that you must first integrate with eHerkenning in a pre-production/sandbox environment before you can go live in a production environment. ::: ## Guides Use the following guides to prepare, configure and set up a connection with eHerkenning. * [**1. Initial preparations**](/identity-methods/eherkenning/integration/initial-preparations): Sign agreements and prepare your Signicat account * [**2. Manage certificates**](/identity-methods/eherkenning/integration/manage-certificates): Create a CSR and purchase PKIoverheid certificates * [**3. Configure eHerkenning in the Dashboard**](/identity-methods/eherkenning/integration/setup-dashboard): Add and configure eHerkenning in the Dashboard * [**4. Set up the eHerkenning service catalogue**](/identity-methods/eherkenning/integration/service-catalogue): Configure your eHerkenning services * [**5. Connect with an authentication protocol**](/identity-methods/eherkenning/integration/connect-authentication-protocols): Connect using OIDC, SAML 2.0 or the Authentication REST API --- ## Initial preparations(3) On this page you find information about the preparatory steps to follow before you can start testing and using eHerkenning. Note that the application process requires communication between your organisation and the Signicat onboarding team. :::warning Pre-production and production It is important to note that you must first integrate with eHerkenning in a pre-production (sandbox) environment before you can go live in a production environment. ::: ## Prerequisites If you are new to Signicat, sign up for a free Signicat account by completing the following initial preparations: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. For more details, see the [Get started with Signicat](/docs/) guide. 2. In the Dashboard, make sure you have set up an [organisation](/docs/dashboard/organisation-management/organisations.mdx). {/* TODO: Add option to test eH with Simulator in eID and Wallet Hub docs */} ## Sign agreements with Signicat To obtain access to Signicat services, you first need to sign contractual agreements with us. The agreements to sign are: 1. An agreement contract 2. A data processing agreement (DPA) Contact us to get started with these agreements: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ## Sign the Self-declaration In order for Signicat to register you in the eHerkenning federation, you need to: 1. Sign the Self-declaration (_Zelfverklaring_) where you indicate that you agree to the demands and agreements in the [eHerkenning federation](https://afsprakenstelsel.etoegang.nl/) (in Dutch). You can find the template document at [Template zelfverklaring Dienstverlener](https://afsprakenstelsel.etoegang.nl/Startpagina/as/template-zelfverklaring-dienstverlener). 2. Send the signed self-declaration to us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. Perform this step for **each service** that you want to create in the eHerkenning and/or eIDAS service catalogue. ## Set up accounts and domains To integrate with eHerkenning in the pre-production environment, you need to set up a sandbox account with a domain in the Signicat Dashboard. To go live in production, you will also need a production account associated with a domain. :::tip Existing accounts If you want to use eHerkenning in an account that you have previously created, you may skip this step. ::: In the [Signicat Dashboard](https://dashboard.signicat.com/), do the following: 1. Create a sandbox account. This is where you set up the pre-production implementation. 2. Create a production account. You will use this when you go live in production. For instructions on how to create an account in the Dashboard, see the [Create an account](/docs/dashboard/organisation-management/accounts.mdx#create-an-account) section. ### Add a domain To handle network communication between your application and the eID and Wallet Hub (which links you to eHerkenning), you need a domain associated to your account(s). When integrating with eHerkenning, you can choose to configure: - A custom domain. A domain with a certificate for your website (for example, `login.acme.com`). - A standard Signicat domain. A domain with a Signicat subdomain address (for example, `example.app.signicat.com`). For instructions on how to create a domain, see the [domains](/docs/dashboard/organisation-management/domains/) documentation. :::tip Domain in combination with DigiD If you also wish to integrate also with DigiD and use [Let's Encrypt](https://letsencrypt.org/) certificates, then you must use a `.nl` domain. Learn more in the [Logius documentation](https://www.logius.nl/domeinen/toegang/digid/documentatie/factsheet-dv-en-ov-certificaten-bij-digid). ::: ## Next steps Once you have completed the steps on this page, you can proceed to create a Certificate Signing Request (CSR) and purchase the PKIoverheid certificates for eHerkenning. * [**2. Manage certificates**](/identity-methods/eherkenning/integration/manage-certificates): Create a CSR and purchase PKIoverheid certificaes --- ## Manage certificates :::warning Important To integrate with eHerkenning, start with the steps described in the [Initial preparations](/identity-methods/eherkenning/integration/initial-preparations.mdx) page. Without following those important steps you may experience delays, technical difficulties and/or even unnecessary expenses. ::: Certificates are used to cryptographically sign the messages between Signicat and the eHerkenning/eIDAS network. To connect to eHerkenning, you must configure: - A certificate for the sandbox account. - A certificate for the production account. To set up the certificates, follow these steps: 1. [Create a Certificate Signing Request](#create-a-certificate-signing-request). 2. [Purchase PKIo certificates](#purchase-pkio-certificates) using Certificate Signing Requests (CSRs). ## Create a Certificate Signing Request A **Certificate Signing Request (CSR)** contains identifying information about your organisation. When applying for a PKIo certificate, you need to create a CSR and share it with a Certificate Authority (CA). Doing this allows the CA to verify your business and issue a PKIo certificate. To create a CSR in the Signicat Dashboard, follow these steps: 1. Go to the **Signicat Dashboard** > [**Organisation management**](https://dashboard.signicat.com/org-mgmt/). 2. Select the account to create a CSR for. 3. In the account management page, select [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 4. In **Certificate Signing Requests**, select **Create**. 5. Fill in the fields in the form: :::CustomTable{columnWidths="25% 20% 30% 25%"} | Information | Distinguished Names | Description | Example | |:------|:------------|:------------|:------------| | Common name | `CN` | The [fully qualified domain name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to secure for your integration. | some.example.com | | Serial number | `SERIALNUMBER` | The [Organisation Identification Number (OIN)](https://www.logius.nl/domeinen/toegang/organisatie-identificatienummer) assigned by Logius to your organisation. This field is compulsory for eHerkenning certificates. | 0000000X123456780000 | | Organisation name | `O` | Registered legal name of your organisation. | Signicat AS | | Organisation unit | `OU` | Internal organisation department/division name | IT | | Country | `C` | The [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) where your organisation is registered. | NL | | Locality | `L` | Town, city, village name. | Amsterdam | | State or Province | `ST` | Province, region, county or state. | Noord-Holland | | Subject Alternative Names | `SAN` | Optional. Provide a FQDN like the Common Name (CN) field or leave empty. | some.example.com | ::: 6. Select **Create** to generate the Certificate Signing Request (CSR) based on the information you submitted. 7. Select **Download** to download the newly created CSR. A CSR is represented as a Base64 encoded string: ```bash -----BEGIN CERTIFICATE REQUEST----- ...Base64-encoded string... -----END CERTIFICATE REQUEST----- ``` Remember that you need to share the CSR with the Certificate Authority (CA) when you apply for a PKIo certificate, as explained in the next step below. ## Purchase PKIo certificates You need to configure your eHerkenning integration with two separate PKIo certificates: - One certificate for the sandbox account. - One certificate for the production account. :::tip What are PKIo certificates? PKIo certificates are Public Key Infrastructure (PKI) certificates used to cryptographically sign messages between Signicat and the network infrastructure of Logius. Learn more about PKIo certificates at [https://cert.pkioverheid.nl/](https://cert.pkioverheid.nl/) and [https://www.logius.nl/english/pkioverheid](https://www.logius.nl/english/pkioverheid). ::: PKIo certificates are required to connect to DigiD, DigiD CombiConnect or eHerkenning. To integrate successfully, you need to purchase and configure two separate certificates: 1. One PKIo certificate for sandbox (preproduction) 2. One PKIo certificate for production :::note Lead time Note that obtaining a new PKIo certificate may take up to *five* working days. ::: #### Supported PKIo certificate types The PKIo certificates must be of one of these types: - **Staat der Nederlanden - G4 Root Priv G-Other - 2024** (until 2039) - G4 Intm Priv G-Other LP - 2024 (recommended) - **Staat der Nederlanden Private Root CA - G1** (until 2028) - Staat der Nederlanden Private Services CA - G1 - **Staat der Nederlanden Root CA - G3** (until 2028) - Staat der Nederlanden Organization Services CA - 2023 - Staat der Nederlanden Organisatie Services CA - G3 #### Certificate providers You can purchase PKIo certificates from any of the Trust Service Providers (TSPs) approved by Logius. For a list of authorised providers, see the [PKIoverheidcertificaat aanvragen](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/pkioverheidcertificaat-aanvragen) page. :::warning Additional requirements for Digidentity certificates To purchase Digidentity certificates, Signicat must first generate the appropriate Certificate Signing Request (CSR) for you. Please contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: :::info Purchase checklist When purchasing PKIo certificates, make sure that: 1. You only use the **Certificate Signing Request (CSR)** obtained in the Signicat Dashboard. If you purchase the certificates independently or without the CSR, your integration will fail. 2. You purchase two separate **PKIoverheid (PKIo)** certificates: one for the sandbox environment and one for the production environment. 3. The type of PKIo certificate is one of the [Supported PKIo certificate types](#supported-pkio-certificate-types). When purchasing a certificate, you should explicitly ask the provider to use the CSR you generated in the Signicat Dashboard. ::: You can find more instructions to guide you with purchasing PKIo certificates from a trusted provider on the Logius website at [PKIoverheid-certificaat aanvragen](https://www.logius.nl/domeinen/toegang/pkioverheidcertificaat-aanvragen). :::info New regulations The importance of certificates is increasing and regulations around certificates are changing. Learn more about the [new generation of PKIo certificates](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/wees-voorbereid-de-nieuwe-generatie-pkioverheidcertificaten-komen-eraan). ::: ## Upload PKIo certificates in the Dashboard Once you have purchased and received the PKIo certificates from a certificate provider, you need to upload the *public* part of the certificates (`.pem` or `.cer` file extension) to the Signicat Dashboard. To upload a PKIo certificate to the Signicat Dashboard, do the following: 1. Navigate to **Account management** > [**Signing Certificates**](https://dashboard.signicat.com/signing-certificates/). 2. In the Signing Certificates section, select **Upload certificate** to upload the PKIo certificate from your device. Alternatively, you can send us the new PKIo certificate either by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or by contacting your onboarding manager. :::note Certificate activation time Please allow up to 4 hours for the certificates to become active and ready for use. If you require expedited processing, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard and request priority handling. ::: :::tip Where to find PKIo certificates in the Signicat Dashboard When you upload a PKIo certificate, you store the (public) PKIo certificate in the Signicat Dashboard infrastructure. To view your certificates, do the following: 1. Go to **Signicat Dashboard** > **Products** > [**eID Hub**](https://dashboard.signicat.com/auth). 2. In the left-side menu, navigate to **Advanced** > **Certificates**. 3. Here, you can review your active certificates and access more details, such as issuer and validity window. ::: ## Next step You are now ready to configure eHerkenning in the Dashboard. * [**3. Add eHerkenning in the Dashboard**](/identity-methods/eherkenning/integration/setup-dashboard): Add and configure eHerkenning in the Dashboard --- ## Service catalogue The service catalogue is the collection of all your eHerkenning services. The services in the catalogue represent specific administrative functions or processes with eHerkenning, such as services to apply for a subsidy or manage parking permits. In the service catalogue, you can add and define multiple services. When adding a service, you need to configure the service name, the level of assurance and the user attributes required by your use case. You can also provide additional information, for example a description with the service purpose. This page guides you through the steps to configure the eHerkenning service catalogue and add a service in the Signicat Dashboard. ## Prerequisites This guide assumes you have already completed the steps in the following guides: 1. [Initial preparations](/identity-methods/eherkenning/integration/initial-preparations.mdx). 2. [Manage certificates](/identity-methods/eherkenning/integration/manage-certificates.mdx). 3. [Add eHerkenning in the Dashboard](/identity-methods/eherkenning/integration/setup-dashboard.mdx). ## Authentication settings :::warning Important The **Authentication settings** must be configured _before_ creating the service catalogue. ::: Before you can create a service in the service catalogue, you need to provide some information about your organisation in the **Authentication settings**. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**Settings**](https://dashboard.signicat.com/auth/settings/). 2. Scroll down to **Metadata settings**. 3. Fill in the following required fields: - Organisation name - Organisation display name - Organisation URL 4. Click **Save** to save the settings. :::warning Important The value of **Organisation display name** MUST match the organisation name in your PKIo certificate, which is derived from the *Organisation name* you provided in the [Create a Certificate Signing Request](/identity-methods/eherkenning/integration/manage-certificates/#create-a-certificate-signing-request) step. ::: :::tip Organisation display name is visible to end-users Note that the organisation display name you enter in the [**Settings**](https://dashboard.signicat.com/auth/settings/) > **Metadata settings** will be visible to the end-users during authentication. ::: Authentication settings ## eHerkenning Service Catalogue After you have configured the [Authentication settings](#authentication-settings), you need to set up your **eHerkenning Service Catalogue**. :::info About the Service Catalogue A Service Catalogue holds information about your eHerkenning services and defines who has access to them. Each service has a ServiceID that is made of an Organisational Identification Number (OIN, or Government Identification Number) and a service index. The OIN matches the value in your PKIo certificate. ::: ### How to add a service to the catalogue To add a new service to the service catalogue, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn) and choose **eHerkenning**. 2. In the eHerkenning configuration page, select **Setup eHerkenning service catalogue**. 3. Select **Add a service**. 4. Select **eHerkenning** as the service type. Note that depending on your use case you can choose between these types of service: - eHerkenning (used by Dutch organisations) - eIDAS (used by European citizens) 5. Configure the service, as explained below in the [eHerkenning service configuration](#eherkenning-service-configuration). 6. When you are ready, select **Add** to create the service. :::warning Activation time Once you add a new service, the changes need to propagate to the eHerkenning network. The process may take up to two hours. When the process is complete, you are ready to connect to the service. ::: #### eHerkenning service configuration The service configuration is comprised of four sections: - General - Certificates - User attributes - Requested attributes Below you find more information about the fields in each category: ##### General - **Configure as portal service**: Tick this box if your organisation has a web service portal that includes multiple eHerkenning services. When ticked, select the name of the portal service to include. - **Select portal services**: Select all the services to include in the configuration for your portal service. - **Service index**: Every service has an index to distinguish it from other services. The index value can be between 1 and 9999. Note that the 0 index is reserved for the portal function in eHerkenning. - **Level of Assurance (LoA)**: Select the desired assurance level. Read more about [which LoA to choose for your services](https://regelhulpenvoorbedrijven.nl/betrouwbaarheiddigitaledienstverlening/). :::CustomTable{columnWidths="25% 25% 50%"} | LoA | eIDAS | SAML 2.0 | | :-- | :---------- | :----------------------------------------- | | 2+ | Low | `urn:etoegang:core:assurance-class:loa2plus` | | 3 | Substantial | `urn:etoegang:core:assurance-class:loa3` | | 4 | High | `urn:etoegang:core:assurance-class:loa4` | ::: - **Service name**: Provide a proper and descriptive name for your service (max 64 characters). The service scope should be clear to the end-users. Make sure you use a unique service name to avoid confusion with other service names. For example, _Apply for a parking permit_. :::warning Service name guidelines It is important that you define a clear service name. For example, the names _Department 1_ or _Municipality X_ may not be clear enough to the users, who should immediately understand the service purpose. For example, if your service is used to apply for a subsidy, name it _Apply for a subsidy_. For help with choosing a service name, contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard or follow the instructions in the official [eHerkenning - Handbooks and support](https://www.eherkenning.nl/en/voor-dienstverleners/aansluiten/handbooks-and-support). ::: - **Service description**: Enter a short description about the scope and purpose of the service (max 1024 characters). - **Service description URL**: Provide a valid URL to your website. This is a link to a public page with additional information about the service and its purpose. - **Support SSO**: Tick this box to enable Single Sign On (SSO). This only applies for LoA lower than 4. ##### Certificate :::note Note This section is only available when you configure encrypted responses. ::: - **Certificate keyname**: The name to help you identify the certificate. - **Upload certificate**: Drag and drop the certificate file or click **Browse files** to upload the (public) PKIo certificate that you want to use to decrypt the eHerkenning payload you receive from Signicat. :::tip PKIo certificate requirements To receive an encrypted response from Signicat, you must upload your (public) PKIo certificate. When you receive an encrypted response, you need to decrypt the payload in your application's backend using the *private* key corresponding to the PKIo certificate. Note that this PKIo certificate is specific to this task and, therefore, different from the PKIo certificate that you upload to establish a connection with eHerkenning. ::: To add more certificates, click **+ Add certificate**. Then, configure the settings above for the new certificate. ##### User attributes {/* TODO: Update names to match name of attributes */} - **I want to receive**: Also known as Entity Concerned Types (ECTAs), these are an Identifier Set and are a combination of one or more identifying attributes. Individual identifiers possible in ECTA sets are: KvK, RSIN, BSN (if allowed), PseudoID, and Pseudo. eIDASLegalIdentifier is currently not yet supported by the EU countries. Here are all the possibilities and combinations per service type: - kvk (eH) - rsin (eH) - bsn (eH / eIDAS) - kvk+rsin (eH) - kvk+bsn (eH) - pseudo (eIDAS) - pseudoid (eIDAS) - bsn+pseudoid (eIDAS) - bsn+pseudo (eIDAS) - bsn+pseudoid+pseudo (eIDAS) - eidasLegalIdentifier (eIDAS) - **+ Add user attributes**: Allows you to add alternative attributes to receive when an attribute you requested is not available. - **Support branch offices**: If you accept login transactions for branch offices the following applies: - You must also accept login transactions without branch office number. - You must respect the restriction to act only for a branch office, to ensure a legally valid legal act has been concluded. - You may not use the branch office to determine the location, only to determine the limits of the power of representation. ##### Requested attributes - **Attributes**: Allows you to request additional attributes. For more information, visit the [attribute catalogue](https://afsprakenstelsel.etoegang.nl/Startpagina/as/attribuutcatalogus) (in Dutch). You can make attributes **Mandatory** or **Optional**. When you choose **Mandatory**, end-users will not be able to log in to your service if they refuse to or they cannot supply the requested attribute. :::warning Important Not all attributes supported by the authentication services or authorisation registries are available. Therefore, make sure to not set attributes that are optional to "Mandatory", since this might prevent a portion of users from logging in. ::: - **Purpose statements**: When you request an attribute, you must provide a purpose statement to explain your end-users the reason for requesting such attribute. - **Privacy policy URL**: When you request an attribute, you must add a valid URL to your privacy policy. This is required by law and the content should follow EU privacy regulations. For more information about the requirements together with advice about the service catalogue configuration, refer to the [official manual](pathname:///uploaded-media/id-methods/eherkenning/HandleidingDienstencatalogusversieVII.pdf) (in Dutch). To learn more about the service catalogue, see the [eHerkenning official manual](https://afsprakenstelsel.etoegang.nl/Startpagina/as/service-catalog). ## Set a default service You can set a service as your default service. By doing this, you automatically route all the authentication flows to the default service. Remember that you can override the default service by passing a parameter in the authentication request. To set the default service, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Choose **eHerkenning**. 3. In the eHerkenning configuration page in the Standard tab, expand the **Default eHerkenning service** dropdown menu and select the name of the service. 4. Click **Save** to set the new default service. :::tip How to override the default service To override the default service in an authentication flow, you need to specify the **service index** as a parameter in the authorisation request. You can find more about what query parameters to use with eHerkenning in the [Attributes reference](/identity-methods/eherkenning/attributes-reference/). ::: ## Next steps If you want to simulate how an authentication flow would look like, you can test your eHerkenning configuration in the Dashboard. * [**Test eHerkenning**](/identity-methods/eherkenning/integration/test-eherkenning): Test an eHerkenning service in the Dashboard When you have configured a service in the catalogue, you can connect your application to eHerkenning by using an authentication protocol. * [**5. Connect with an authentication protocol**](/identity-methods/eherkenning/integration/connect-authentication-protocols/): Establish a connection with OIDC, SAML 2.0 or the Authentication API --- ## Add eHerkenning in the Dashboard This page describes how to configure eHerkenning in the Signicat Dashboard. After completing these steps, you will be ready to define your services in eHerkenning the service catalogue. ## Prerequisites :::warning Required steps To integrate with eHerkenning in the Signicat eID and Wallet Hub, start with the prerequisite guides listed below. ::: This guide assumes you have completed the following steps: 1. [Initial preparations](/identity-methods/eherkenning/integration/initial-preparations.mdx). 2. [Manage certificates](/identity-methods/eherkenning/integration/manage-certificates.mdx). :::note Sandbox and production accounts We recommend you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ## Add eHerkenning To add a new eID in your Signicat account, you need to configure and activate the eID in the Dashboard. Once Signicat has given you access to eHerkenning, you can activate it in the Dashboard. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **+ Add new**. 3. Choose **eHerkenning** from the list. Now, configure the eHerkenning settings, as explained in the [Set up eHerkenning configuration](#set-up-eherkenning-configuration) section below. Choose eHerkenning ### Set up eHerkenning configuration In the eHerkenning configuration page, you can adjust the following settings: :::CustomTable{columnWidths="20% 20% 60%"} | Setting | Level | Description | |:--------|:--------|:----------- | | Organisation Identification Number (OIN) | Standard | Prefilled based on your PKIo certificate. | | Entity index | Standard | The connection index. A number between 1 and 9999. Often 9001 for the sandbox environment and 1 for the production environment. | | Default eHerkenning service | Standard | Optional. Allows you to set a default eHerkenning service so that your end-users automatically log in to this service when you do not specify any service index in the authentication request. Note that you first need to add a service in the [eHerkenning service catalogue](/docs/identity-methods/eherkenning/integration/service-catalogue.mdx). | | Select attribute filter | Advanced | Optional. Select an attribute filter to control which attributes to include, or exclude, from the response. To create attribute filters in the Dashboard, navigate to **Products** > **eID and Wallet Hub** > **Advanced** > [**Attribute filters**](https://dashboard.signicat.com/bca/attribute-filters). | | Include only when scoped | Advanced | Optional. If ticked, eHerkenning will _not_ be displayed on the eID selection screen by default, unless you specify it using IdP discovery. With IdP discovery, you add a query parameter in your request to control which eIDs are available for authentication. This is useful when you have multiple eIDs active in your account and you only want to offer a subset to your end-users. | | Do not use eHerkenning Idp SSO | Advanced | Optional. If ticked, you always prompt the user to log in. Also, the logout flow will redirect the user to your website instead of the eHerkenning IdP page, if you have configured the relevant logout URLs. **Note** that this setting does not affect other types of SSO configured in your Signicat account. | | Response attribute mapping | Advanced | Optional. Allows you to map the name of any attribute in the response to a custom name of choice. | ::: ### Save eHerkenning configuration To save your configuration and add eHerkenning to your eIDs, select **Add**. You should now view eHerkenning listed with status "Active" in the eIDs page. ## Register your eHerkenning configuration After you add eHerkenning, a metadata file is generated. The file contains information about the configuration. Please send us the metadata file to register your connection in the eHerkenning network. To do this: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **eHerkenning**. 3. In the eHerkenning configuration page, click **Get Signicat metadata** to view the metadata file in XML format. 4. Copy the URL of your metadata file and send this to us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. Registering your configuration in the eHerkenning network allows you to define and create a service in the service catalogue. ## Next steps You are now ready to set up the service catalogue: * [**4. Set up the eHerkenning service catalogue**](/identity-methods/eherkenning/integration/service-catalogue): Configure your eHerkenning services --- ## Test eHerkenning You can test an eID in the Dashboard. Testing allows you to simulate the steps that your end-users follow when authenticating to your digital services. Note that testing an eID in the Dashboard does not require an authentication protocol. However, you should also test your integration with an authentication protocol, before going live in production. ## Prerequisites This guide assumes you have completed the steps in these guides: 1. [Initial preparations](/identity-methods/eherkenning/integration/initial-preparations.mdx). 2. [Manage certificates](/identity-methods/eherkenning/integration/manage-certificates.mdx). 3. [Add eHerkenning in the Dashboard](/identity-methods/eherkenning/integration/setup-dashboard.mdx). 4. [Set up a service in the service catalogue](/identity-methods/eherkenning/integration/service-catalogue.mdx). :::warning Add a default service To test a service in the Dashboard, you must first set a default service in the eHerkenning configuration. For instructions on how to do this, see the [Set a default service](/docs/identity-methods/eherkenning/integration/service-catalogue.mdx#set-a-default-service) section. ::: ## Test eHerkenning in the Dashboard To test an eHerkenning authentication flow in the Dashboard, do the following: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right corner. 3. Optional. Choose eHerkenning from the identity provider selection screen. This applies only if you have multiple eIDs enabled in your account. 4. In the "Choose how to log in" page, choose the eHerkenning supplier that you wish to authenticate with. 5. Follow the instructions on the login page of the eHerkenning supplier. The steps vary depending on the supplier you choose. To view an example that uses WeID as a supplier, continue to the next section below. ## Example of user journey with WeID If you use WeID as a supplier, your authentication flow would look like this: :::note Select organisation Note that steps 7 and 8 in the flow above are optional and depend on the organisations a user can log in on behalf of. These are defined in the eHerkenning profile of the user and do not depend on your integration. ::: ## Text on the UI When a user authenticates with your app using eHerkenning, the UI displays text that contains information such as: - Your organisation name - Level of Assurance (LoA) - Service name You can view an example of UI text in the web screens displayed above in the [Example of user journey with WeID](#example-of-user-journey-with-weid) section. In particular, note the following sentences: - "You wish to log in to **Signicat** 1 for **Apply for a subsidy** 2. To do this you need an authentication method of at least **level of assurance EH2** 3." - "Log in to **Signicat** 1 for **Apply for a subsidy** 2" - "On behalf of **Example Organisation Name B.V.** 4 you can use the service **Apply for a subsidy** 2 at **Signicat** 1" In the examples above, the following strings map to values in your service configuration: 1. **Signicat**: The name of your organisation. You set this in the **eID and Wallet Hub** > [**Settings**](https://dashboard.signicat.com/bca/settings/edit). 2. **Apply for a subsidy**: Service name. 3. **level of assurance EH2**: Level of Assurance. 4. **Example Organisation Name B.V.**: Optional. The organisation(s) that the user logs in on behalf of. The list here shows the organisations an end-user is a member of. This depends on the eHerkenning profile of the user. ## Next steps To connect your application to eHerkenning you need to integrate with an authentication protocol. * [**5. Connect with an authentication protocol**](/identity-methods/eherkenning/integration/connect-authentication-protocols/): Establish a connection with OIDC, SAML 2.0 or the Authentication API --- ## About Email OTP Signicat's Email OTP is an authentication method based on one-time passwords (OTP) sent by email. ## Use cases When an end-user wants to access your application that requires authentication, a typical scenario consists of the following steps: :::note Scenario 1 - Your application backend starts an authentication session with Signicat Email OTP and directs the user to the authentication page. - The end-user enters their email address in the Email OTP authentication page. - Signicat Email OTP sends an email with an OTP code to the end-user. - The end-user uses the code to successfully authenticate. - You receive the end-user's email address as part of the response from Signicat. ::: In cases when you already know the email address of an end-user and the end-user wants to access your application, the scenario changes to: :::note Scenario 2 - Your application backend starts an authentication session with Signicat Email OTP and directs the user to the authentication page. - Signicat Email OTP sends an email with an OTP code to the end-user. - The end-user uses the code to successfully authenticate. - You receive a confirmation (true or false) in the response from Signicat. ::: Although Email OTP alone does not provide a high level of security, from a technical standpoint there is nothing that prevents you from using it as a standalone authentication method. However, it is more common and recommended to use Email OTP to boost an existing login process. In fact, Email OTP combined with any username/password-based login solution forms a two-factor authentication method. ## Technical details Here are some technical details about Email OTP: - An OTP code is _six_ characters long. The code is a string of numerical digits. For example, `012345`. - An OTP code is valid for _three_ minutes. After that time, the OTP code expires and the end-user must request a new one. - The end-user can request up to _three_ OTP codes within an authentication session. The authentication session window lasts for five minutes. After that, the end-user needs to start over. - An end-user has _three_ attempts to enter the correct code. If authentication fails, the end-user needs to start over. - User authentication expires after 24 hours. After that time, the end-user receives a new OTP code when they try to access the service. Authentication expiration ensures additional security. ## Language support Signicat Email OTP supports authentication flows in the following languages: - Czech - Danish - Dutch - English (default) - Finnish - French - German - Greek - Italian - Norwegian - Polish - Spanish - Swedish You can define the language displayed on the screens during an authentication session with Email OTP. Learn more in the [UI language](/identity-methods/email-otp/code-examples/#ui-language) page. ## User journey When authenticating with Email OTP, the user journey looks like this: Ready to see it in action? Follow the steps in the [Setup guide](/identity-methods/email-otp/setup/) to configure Email OTP in the Dashboard. --- ## Attributes reference(Email-otp) You use Email OTP to authenticate your end-users with a one-time password (OTP) sent by email. After authentication, you can receive their email address. This page shows scopes, attributes and response examples for each authentication protocol: - [OpenID Connect (OIDC)](#oidc-scopes-and-claims) - [Signicat Authentication REST API](#signicat-authentication-rest-api-attributes) - [SAML 2.0](#saml-20-attributes) ## OIDC scopes and claims :::CustomTable{columnWidths="20% 20% 40% 20%"} | **Scope** | **Claim** |**Description** | **Example** | | :--------- | :----------- | :---------------------------------- | :-------------- | | `openid` | `idp_issuer` | The IdP used during authentication. | `otp-email` | | `idp-id` | `idp_id` | The email address of the user, as raw subject. | `signikitten@example.com` | | `email` | `email` | The email address of the user. | `signikitten@example.com` | ::: #### OIDC request example To trigger an authentication, you build an OIDC request like: ```http https:///auth/open/connect/authorize? &client_id= &response_type=code &redirect_uri= &state=1599045135410-jFe &scope=openid%20idp-id%20email &acr_values=idp:otp-email &prompt=login &ui_locales=en &nonce=1599046102647-dv4 ``` #### OIDC response example Below, you find an example of a response example for the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. Scopes in request: `openid`, `idp-id`, `email` Response example: ```json { "idp_id": "signikitten@example.com", "sub": "TOuh-Q-Qx2-EBXT3a3OgaoGXgQSx55ggpIXXXXXX", "idp_issuer": "otp-email", "email": "signikitten@example.com", } ``` ## Signicat Authentication REST API attributes The Signicat [Authentication REST API](/apis/eid-hub/) supports the following request and response attributes for Email OTP: :::CustomTable{columnWidths="33% 33% 33%"} | Attributes | Example | Description | | :------------------------ | :--------------------------- | :--------------------------- | | `idpId` | `signikitten@example.com` | The email address of the user, as raw subject.| | `email` | `signikitten@example.com` | The email address of the user.| ::: #### Authentication API request example To create a session using the Authentication REST API, you send a POST request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. This is `https://api.signicat.com/auth/rest/sessions`. You define the parameters of the session in the payload of the request. For example: ```json { "allowedProviders": [ "otp-email" ], "flow": "redirect", "language": "en", "requestedAttributes": [ "idpId", "email" ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` #### Authentication API response example The following is an example of a response: ```json { ... "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56", "status": "SUCCESS", "provider": "otp-email", "subject": { "id": "X6hYgXvTvNMf27-mC0cYzOUb4HBWR1feCSh5Ul7KiNQ=", "idpId": "signikitten@example.com", "email": "signikitten@example.com", } ... } ``` ## SAML 2.0 attributes :::CustomTable{columnWidths="33% 33% 33%"} | SAML 2.0 Protocol Attribute | Example | Description | |-----------------------------|-----------------------------|------------------------------| | `idpId` | `signikitten@example.com` | The email address of the user, as raw subject.| | `email` | `signikitten@example.com` | The email address of the user.| ::: #### SAML 2.0 service provider metadata document The example below shows a Service Provider (SP) metadata document to connect to Email OTP and request the attributes: `idpId`, `email`. ```xml All attributes ``` #### SAML 2.0 request example SAML 2.0 request example: ```xml ENTITY_ID ``` #### SAML 2.0 response example SAML 2.0 response example: ```xml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml https://*YOUR_SIGNICAT_DOMAIN*/auth/saml ... SIGNATURE_VALUE X509_CERTIFICATE OZWWk8DKdFYf1JzLU8zJtku0uXkPaLvnIt ENTITY_ID signikitten@example.com signikitten@example.com substantial otp-email ``` ## UI language :::info Default language By default, the language property is set to English. ::: Email OTP supports the following languages in ISO 639-1 format: :::CustomTable{columnWidths="50% 50%"} | Language | Parameter | | :-------- | :-------- | | Czech | `cs` | | Danish | `da` | | Dutch | `nl` | | English (default) | `en` | | Finnish | `fi` | | French | `fr` | | German | `de` | | Greek | `el` | | Italian | `it` | | Norwegian | `no` | | Polish | `pl` | | Spanish | `es` | | Swedish | `sv` | ::: ### How to edit the language settings To edit the language displayed on the user interface (UI) of Email OTP during an authentication session, you need to follow the syntax specific to each authentication protocol. Below, you can find examples for each case: To change the language of the UI, you need to define the query string parameter `ui_locales` in your OIDC authorization request. For example, you can set the language to Greek (`ui_locales=el`) by passing the following in your request: ```bash {5} https:///auth/open/connect/authorize? &client_id=OIDC_CLIENT_ID &response_type=GRANT_TYPE_CODE &redirect_uri=REDIRECT_URI &ui_locales=el &scope=OIDC_SCOPES ``` To change the language of the UI, you need to specify the language by using the `signicat:param:language` parameter in the SAML `AuthnRequest` Extensions. For example, you can set the language to Greek (`el`) by passing the following in your request: ```xml {4,10} el ``` To change the language of the UI, you need to specify the `language` parameter in the payload of your request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, you can set the language to Greek (`"language": "el"`) by passing the following in your request: ```json {3} { "flow": "redirect", "language": "en", ... "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` --- ## Email OTP Signicat's Email OTP is an authentication method based on one-time passwords (OTP) sent by email. If you want to read more high-level documentation about Email OTP before you start the integration, see [About Email OTP](/identity-methods/email-otp/about-email-otp.mdx). ## Get started * [**Setup of Email OTP**](/identity-methods/email-otp/setup/): Set up the eID and control the flow * [**Attributes reference**](/identity-methods/email-otp/code-examples/): See response code examples and parameter descriptions ## Tell me more * [**About Email OTP**](/identity-methods/email-otp/about-email-otp): High-level information about Email OTP ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Embedded flow This guide shows you how to set up an integration with Email OTP, using the Signicat Authentication REST API with [embedded flow](/docs/eid-hub/authentication-api/#embedded-flow). An embedded flow allows you to include the authentication flow inside an iframe in your application (as opposed to the redirect flow where you are redirecting the user to another page). In an embedded flow, the authentication journey happens inside a component, like an iframe, embedded within your UI. In this scenario, your application manages the iframe and the end-user redirect, creating a hybrid integrated experience. ## How it works The Signicat Authentication REST API enables you to create embedded flows for user authentication. This approach is designed to be rendered within an iframe, allowing the end-user to complete an authentication journey without leaving your application. #### Iframe The ` ``` :::tip What is an iframe? An ` ``` The width and height attributes on the ` ``` :::warning Iframe size requirements To ensure that all Email OTP pages are framed correctly, make sure you set the following minimum dimensions: - Min size is 350px x 600px - Recommended min size for desktop devices is 450px x 650px ::: ### Step 2. Test an authentication You can quickly test the embedded flow without having to build a custom frontend application. You achieve this by starting an authentication session with the Authentication REST API and passing the `authenticationUrl` in an iframe in an online HTML tester, such as the **W3Schools Tryit Editor**. To test the iframe in a custom HTML test page, do the following: 1. Go to [this project](https://www.w3schools.com/html/tryit.asp?filename=tryhtml_iframe) in the W3Schools Tryit Editor. :::tip Template HTML code To test the flow on a minimal HTML page, use the template HTML code below: ```html HTML Iframes An iframe is used to display a web page within a web page: ``` ::: 2. In the template HTML code, edit the `src` attribute in the ` ``` :::tip What is an iframe? An ` ``` The width and height attributes on the ` ``` :::warning Iframe size requirements To ensure that all SMS OTP pages are framed correctly, make sure you set the following minimum dimensions: - Min size is 350px x 600px - Recommended min size for desktop devices is 450px x 650px ::: ### Step 2. Test an authentication You can quickly test the embedded flow without having to build a custom frontend application. You achieve this by starting an authentication session with the Authentication REST API and passing the `authenticationUrl` in an iframe in an online HTML tester, such as the **W3Schools Tryit Editor**. To test the iframe in a custom HTML test page, do the following: 1. Go to [this project](https://www.w3schools.com/html/tryit.asp?filename=tryhtml_iframe) in the W3Schools Tryit Editor. :::tip Template HTML code To test the flow on a minimal HTML page, use the template HTML code below: ```html HTML Iframes An iframe is used to display a web page within a web page: ``` ::: 2. In the template HTML code, edit the `src` attribute in the ` ``` 3. On the top navigation bar of the W3Schools Tryit Editor, click **Run** to execute the script. 4. Now, the SMS OTP service starts an authentication flow inside the rendered iframe. 5. Follow the steps to complete the authentication flow by providing an phone number and entering the received OTP code. 6. Once the authentication completes successfully, the iframe will redirect the end-user to the `returnUrl` value you provided when creating the session. Example of testing environment using the W3Schools Tryit Editor: Test authentication with SMS OTP in iframe :::note Considerations for testing on Firefox Mobile Online HTML editors use dynamic iframe injection that Firefox Mobile evaluates very strictly. To test the embedded flow using an online HTML editor on Firefox Mobile, you must adjust your request as follows: - W3Schools Tryit Editor: Omit `embeddedParentDomains` entirely (defaults to `*`) - CodePen: Set `embeddedParentDomains` to `["cdpn.io", "codepen.io"]` Note that this workaround only applies to testing environments. When embedding the iframe into your own production application, these considerations do not apply. ::: :::warning Third-party cookies Note that it is important that the end-user's browser has third-party cookies enabled for the authentication flow to work. Learn more about cookies and browser compatibility in the [Browser requirements](#browser-requirements) section. ::: #### User journey The user journey inside the iframe looks like this: ### Step 3. Receive the sessionNonce Upon successful authentication, the iframe content is redirected to the `returnUrl` that now contains the `sessionNonce` as a query parameter. To obtain the authentication result, you need to extract the `sessionNonce` query parameter from the `returnUrl`. Once you receive the `sessionNonce`, you may then implement how you want your application to handle the iframe and further redirect the end-user. #### Parse the returnUrl The return URL follows the `https://{returnUrl}/?sessionNonce=` format. For example, if the `returnUrl` you sent in your request was `https://www.example.com`, then you would receive the following request back in the iframe: ```curl title="Return URL with sessionNonce" https://www.example.com/?sessionNonce=V2G_GwOfuCTNQohLn_MyvJ99mQJT7UKmJ_pmaZdVQg0 ``` Your application needs to extract the `sessionNonce` from the query parameter of the return URL. Then, you use the `sessionNonce` to retrieve the session status. When an authentication is successful, the session status response contains the end-user's personal information. ### Step 4. Get the session status After creating an authentication session with the Signicat Authentication REST API, you can call the [Get session status endpoint](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) to retrieve the status of the session, which indicates whether the flow has started, failed or completed. #### Request To receive the status of a session, send a GET request to `https://api.signicat.com/auth/rest/sessions/{id}?sessionNonce={sessionNonce}`. - `id`: The session identifier. You find the session `id` value in the initial response you received when creating the session. - `sessionNonce`: Note that for an embedded flow you need to provide the extracted `sessionNonce` value as a query parameter. - No data specific to SMS OTP needs to be included in this request. **Example request** ```curl title="Get session status request for embedded flow" curl --location 'https://api.signicat.com/auth/rest/sessions/?sessionNonce=' \ --header 'Authorization: Bearer eyJ...' ``` In the response example above, the session `id` is `558b1459-335c-4431-8561-b44d9c727bb9` so the request would be: ```curl title="Example of Get session status request for embedded flow" curl --location 'https://api.signicat.com/auth/rest/sessions/558b1459-335c-4431-8561-b44d9c727bb9?sessionNonce=V2G_GwOfuCTNQohLn_MyvJ99mQJT7UKmJ_pmaZdVQg0' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer eyJhbGc...' ``` :::note `sessionNonce` is required Note that you can only request the status of the session after you have received the `sessionNonce` as a query parameter to the `returnUrl`. :::: #### Response The response you receive from the API contains a `status` field that informs you about the current status of the authentication session. ##### Status overview The `status` field returns one of the following values: :::CustomTable{columnWidths="25% 75%"} | **Status** | **Description** | | :----------------- | :----------------------------------------------------------- | | `SUCCESS` | The authentication was successful. Authentication result is present in the response. | | `ABORT` | The session was cancelled by the end-user. | | `ERROR` | The SMS OTP session was not completed in time. | ::: ##### Successful authentication When the authentication session is successful, you receive a `SUCCESS` status. Importantly, you receive the personal information of the end-user in the `subject` field (JSON object) of the response. For example, the response for a successfully completed session is: ```json title="Example of a successful status response for embedded flows" { "id": "558b1459-335c-4431-8561-b44d9c727bb9", "accountId": "a-sdge-...", "authenticationUrl": "https://api.signicat.com/idps/otp/sms?lang=en&transactionId=da4a08f6-3fd8-bb4d-bc5a-7ea11ee80176&messageId=a75d711f-9774-4e69-90d5-2531ed720d41", "status": "SUCCESS", "provider": "otp-sms", "subject": { "id": "TOuh-Q-Qx2-XXXXXXXX", "idpId": "447700900000", "phoneNumber": "447700900000" }, "loa": "low", "allowedProviders": [ "otp-sms" ], "language": "en", "flow": "embedded", "requestedAttributes": [ "phoneNumber", "idpId" ], "sessionLifetime": 1200, "expiresAt": "2026-03-25T14:17:21.5008041+00:00" } ``` Note that the `subject` object contains the personal information of the end-user. The values you receive match the attributes that your requested when you first created the authentication session. Learn more about the different attributes you can specify in your request to SMS OTP in the [Attributes reference](/identity-methods/sms-otp/code-examples.mdx) documentation. :::note Success You have now completed the embedded flow with SMS OTP using the Signicat Authentication REST API. ::: #### Handling the authentication response Upon receiving the end-user's personal information, your application's backend is ready to identify the end-user. How you do this depends on your use case for digital identity. Once you have processed the personal information of the user and achieved your identity verification goal, you are ready to instruct your application's frontend to continue to the next screen, depending on your application's logic and design. ## Browser requirements To ensure a successful implementation of the embedded flow in your application, we recommend you consider the following browser requirements. ### SameSite attribute and third-party cookie blocking To maintain a consistent user session across the authentication steps within the iframe, we set a session cookie. However, because the iframe loads content from a different domain than your application, this cookie is treated as a cross-site, or third-party, cookie. This presents two significant challenges that your integration needs to address. 1. **Cross-Site Request Forgery (CSRF) risk:** To function in a cross-site context, we must set the `SameSite` attribute of the session cookie to `None`. While this enables the embedded flow, it also removes the browser's default CSRF protections, creating a potential security vulnerability that you need to mitigate. 2. **Third-party cookie blocking:** Modern browsers are phasing out support for third-party cookies to address privacy concerns and prevent ad-tracking. When a browser blocks third-party cookies, the embedded session is interrupted and the user cannot proceed with the authentication flow. To solve both of these challenges simultaneously, Signicat's embedded flow implements Cookies Having Independent Partitioned State (CHIPS), as explained below. #### CHIPS [CHIPS](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies) is a modern browser standard that allows a third-party service (like Signicat) to set a cookie that is "partitioned" by the top-level domain (your application). With CHIPS, the browser securely binds the "partitioned" cookie to the top-level domain (your application) active at the exact moment the cookie was issued. This effectively isolates the cookie, preventing its misuse in other contexts. CHIPS solves both challenges: it mitigates third-party cookie blocking and prevents login CSRF attacks. There is no additional implementation required on your part to enable CHIPS; it is handled automatically by Signicat's authentication service and supported by modern browsers. ##### Browser compatibility and monitoring Because CHIPS is a relatively new web standard, it requires users to have an up-to-date browser. As of 2025, CHIPS is supported by all major browsers, except for Android WebView. :::note Browser compatibility For information about supported browsers, visit the CHIPS [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies#browser_compatibility) page. Note that a bug in Safari resulted in CHIPS support being temporarily disabled in Safari between March 2025 and December 2025. ::: If your end-users encounter frequent errors due to third-party cookie limitations, we recommend you adopt alternative session-handling workarounds until CHIPS-compatible browsers gain broader adoption. Alternative workarounds include embedding a custom session token in the page and manually appending it to HTTP request headers or POST bodies. If you require assistance, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ## Security considerations To protect your implementation from fraudulent attacks, make sure you adhere to the [Security measures](/identity-methods/sms-otp/setup/security-measures.mdx). ## Advanced configuration ### Theming The pages of the embedded flow render with the default Signicat theme. Support for custom theming of the embedded pages is planned for a future release. To stay up to date with upcoming feature releases, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ### Set the UI language To change the language on the SMS OTP UI, use the `language` parameter in the payload of your request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, use `"language": "el"` to set the SMS OTP UI to Greek. :::info Default language By default, the UI language is English. ::: For an overview of the languages supported, see the [UI language](/identity-methods/sms-otp/code-examples/#ui-language) page. ### Prefill user information When using the Signicat REST API, you pass user data in the `prefilledInput` field in the payload of the request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint, so that the end-user does not have to enter their phone number manually when authenticating. For example, this applies to cases when you already know the phone number. To specify a phone number in the authentication URL, the payload of the request might looks like this: ```json ... "prefilledInput": { "mobile": "+447700900000", }, ... ``` This will display the phone number to the end-user when they start the authentication flow. To learn more about data prefilling, see the [Prefilling user information](/docs/eid-hub/concepts/prefilling-information/) conceptual guide. :::warning Verify the phone number For security reasons, we recommend you verify that the phone number you receive in the response from SMS OTP matches the phone number you prefilled in the authentication URL. ::: ### Attributes For an overview of the attributes available for SMS OTP, see the [Attributes reference](/identity-methods/sms-otp/code-examples/). ## Next steps Learn more about Signicat Authentication REST API flows and endpoints in the [Authentication REST API documentation](/docs/eid-hub/authentication-api/). --- ## Integration with Authentication REST API(Authentication-api) You can integrate with SMS OTP using the Signicat Authentication REST API as an authentication protocol. ## Integration guides The guides below provide all the steps to set up your connection using either the **redirect** or **embedded** flows. * [**Redirect flow**](/identity-methods/sms-otp/setup/authentication-api/redirect): Integrate with SMS OTP using the redirect flow * [**Embedded flow**](/identity-methods/sms-otp/setup/authentication-api/embedded): Integrate with SMS OTP using the embedded flow :::tip eID and Wallet Hub documentation If you want to read more about the basics of Signicat Authentication REST API before you start integrating with SMS OTP, see the: - [Authentication REST API](/docs/eid-hub/authentication-api/) documentation for a conceptual description of the flows. - [API Reference](/apis/eid-hub/) for endpoint descriptions. ::: --- ## Redirect flow(Authentication-api) This guide shows you how to set up an integration with SMS OTP, using the Signicat Authentication REST API with [redirect flow](/docs/eid-hub/authentication-api/#redirect-flow). ## Prerequisites 1. Follow the steps on the [Configure SMS OTP](/identity-methods/sms-otp/setup/configuration/) page to establish a connection with SMS OTP. 2. Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see **Connect to Signicat APIs** [Quick start guide](/docs/dashboard/connect-to-signicat-apis/quick-start-guide.mdx). > Ensure that you set the **Authentication REST API** permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide. :::info Learn more about the Signicat Authentication REST API - [Authentication REST API](/docs/eid-hub/authentication-api/) for conceptual documentation. - [API Reference](/apis/eid-hub/) for endpoint descriptions. ::: ## Implementation This section details how to set up authentication for SMS OTP using the *redirect flow*. A redirect flow allows you to route your end-users to an authentication URL which opens an authentication journey in a web browser. ### 1. Create a session To initiate an authentication flow, you need to send a request to the Signicat Authentication REST API and create a session. #### Request To create a session in the Authentication REST API, you send a POST request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. The `/sessions` endpoint allows you to create a new session and begin an authentication flow. This is `https://api.signicat.com/auth/rest/sessions`. For example, your request payload could look like this: ```json { "allowedProviders": ["otp-sms"], "flow": "redirect", "requestedAttributes": [ "idpId", "phoneNumber" ], "language": "en", "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` Consider the following fields in the payload of the request: :::CustomTable{columnWidths="20% 20% 20% 40%"} | **Field** | **Required** | **Example value** | **Description** | | :-------------------| :------------| :-------------------| :-------------------------------| | `allowedProviders` | No | `["otp-sms"]` | Specify `["otp-sms"]` to show end-users only SMS OTP. Don't send this field if you want to display a list of all the eIDs enabled in your account. | | `flow` | Yes | `redirect` | MUST have the value `redirect`. | |`language` | No | `en` | ISO 639-1 language tag to set the language of the UI (English, by default). For an overview of the languages supported, see the [UI language](/identity-methods/sms-otp/code-examples/#ui-language) page. | |`requestedAttributes`| Yes | `["idpId", "phoneNumber"]` | The attributes you wish to get back from the authentication of the end-user. The `phoneNumber` attribute returns the same phone number as `idpId` (subject). | ::: For more information about the "Create a session" endpoint, see the [API Reference](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) description. You can find an overview of attributes and responses in the [Attributes](/identity-methods/sms-otp/code-examples/) page. ##### Additional parameters When sending requests to the Signicat [Authentication REST API](/apis/eid-hub/), you can customise end-user authentication with the `additionalParameters` field. The key-values you define in the `additionalParameters` field vary depending on the eID. SMS OTP supports the following parameters: :::CustomTable{columnWidths="25% 50% 25%"} | **Key** | **Description** | **Value example** | |:---------------- |:-------------------------------------------------------------------------------- |:----------------- | | `otp_sms_sender` | Overrides the SMS sender name displayed to the recipient for a specific request. | `Signicat AS` | ::: Example in a request payload: ```json ... { "additionalParameters": { "otp_sms_sender": "Signicat AS" } } ... ``` :::tip Display SMS OTP only To direct the end-user to SMS OTP, skipping the eIDs selection screen, you can use the `"allowedProviders": ["otp-sms"]` parameter in the payload of your request. This prevents users from choosing other eIDs that may be active in your account. ::: #### Response Here is an example response after you have created a session: ```json {4,5,12,14,16} { "id": "58126fb8-c5e2-...", "accountId": "a-sdge-...", "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=21b064c3-28b...", "status": "CREATED", "callbackUrls": { "success": "https://example.com/success?sessionId=58126fb8-c5e2...", "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...", "error": "https://example.com/error?sessionId=58126fb8-c5e2..." }, "allowedProviders": [ "otp-sms" ], "flow": "redirect", "requestedAttributes": [ "idpId", "phoneNumber" ], "language": "en", "sessionLifetime": 600 } ``` #### Use the response You must redirect the end-user to the `authenticationUrl` found in the response. This is a unique URL which allows the end-user to perform the SMS OTP authentication in context of the session you just created. #### User journey When end-users access the authentication URL, the user journey looks like this: When the end-user completes the authentication flow, they are automatically redirected to the `callbackUrls`, depending on the outcome of the authentication. ### 2. Get the session status #### Request To get the status of a session, send a GET request to `https://api.signicat.com/auth/rest/sessions/{id}`. You can find the `id` value in the response that was returned when you created the session. No data specific for SMS OTP needs to be included in this request. For more information about the "Get session status" endpoint, see the [API Reference](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/GetSession) description. #### Response The response contains a `status` field that informs you about the current status of the session. For example, the response for a successfully completed session is: ```json { "id": "58126fb8-c5e2-...", "accountId": "a-sdge-...", "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=21b064c3-28b...", "status": "SUCCESS", "provider": "otp-sms", "language": "en", ... } ``` ##### Status overview :::CustomTable{columnWidths="25% 75%"} | **Status** | **Description** | | :----------------- | :----------------------------------------------------------- | | `WAITING_FOR_USER` | The end-user has not started to authenticate yet. | | `SUCCESS` | The authentication was successful. Authentication result is present in the response. | | `ABORT` | The session was cancelled by the end-user. | | `ERROR` | The SMS OTP session was not completed in time. | ::: #### Use the response If the returned status is `SUCCESS`, the `subject` object contains information about the authenticated user. ```json {7-10} { "id": "XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX", "accountId": "", "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=XXXXXXXX-fb55-bd4e-8dbc-XXXXXXXX&transactionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX", "status": "SUCCESS", "provider": "otp-sms", "subject": { "id": "TOuh-Q-Qx2-XXXXXXXX", "idpId": "+447700900000", "phoneNumber": "447700900000" }, "callbackUrls": { "success": "https://example.com/success?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX", "abort": "https://example.com/abort?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX", "error": "https://example.com/error?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX" }, "environment": { "ipAddress": "192.0.2.2", "userAgent": "" }, "allowedProviders": [ "otp-sms" ], "flow": "redirect", "requestedAttributes": [ "idpId", "phoneNumber" ], "language": "en", "sessionLifetime": 600 } ``` In the object you can also see the service provider specified in the `provider` field. This can be useful if you specified more than one provider when you created the session. ### Set the UI language To change the language on the SMS OTP UI, use the `language` parameter in the payload of your request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint. For example, use `"language": "el"` to set the SMS OTP UI to Greek. For an overview of the languages supported, see the [UI language](/identity-methods/sms-otp/code-examples/#ui-language) page. ### Prefill user information When using the Signicat REST API, you pass user data in the `prefilledInput` field in the payload of the request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint, so that the end-user does not have to enter their phone number manually when authenticating. For example, this applies to cases when you already know the phone number. To specify a phone number in the authentication URL, the payload of the request might looks like this: ```json ... "prefilledInput": { "mobile": "+447700900000", }, ... ``` This will display the phone number to the end-user when they start the authentication flow. To learn more about data prefilling, see the [Prefilling user information](/docs/eid-hub/concepts/prefilling-information/) conceptual guide. :::warning Verify the phone number For security reasons, we recommend you verify that the phone number you receive in the response from SMS OTP matches the phone number you prefilled in the authentication URL. ::: ### Attributes For an overview of the attributes returned by SMS OTP, see the [Attributes mapping for the Authentication REST API](/identity-methods/sms-otp/code-examples/). ## Security considerations To protect your implementation from fraudulent attacks, make sure you adhere to the [Security measures](/identity-methods/sms-otp/setup/security-measures.mdx). ## Next steps Learn more about Signicat Authentication REST API flows and endpoints in the [Authentication REST API documentation](/docs/eid-hub/authentication-api/) --- ## Configure SMS OTP With the Signicat SMS OTP service, you can perform SMS-based user authentication. This page describes how to configure SMS OTP on the [Signicat Dashboard](https://dashboard.signicat.com/). :::info Want to learn more? For general information about integrating with Signicat, see the **eID and Wallet Hub** [Quick start guide](/docs/eid-hub/quick-start/). ::: ## Prerequisites If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ## Add SMS OTP To use an eID, you first need to activate it. In the Signicat Dashboard: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **+ Add new** in the top right. 3. Choose **SMS OTP** from the list. 4. Select **Add** to activate the eID. SMS OTP should now appear in the list of available eIDs with the status set to "Active". ## Test SMS OTP in the Dashboard After you activate SMS OTP, you can simulate an authentication flow in the Signicat Dashboard. :::note Test message warning If you are testing our services with a sandbox account, then we prepend all emails and SMS messages with a [Test message warning](/docs/dashboard/branding/communication.mdx#what-does-a-test-message-look-like). ::: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** on the top-right side. 3. Optional. If you have multiple eIDs active in your account, select SMS OTP from the list of identity providers. 4. Enter your phone number, then select **Next**. 5. Open the messenger app in your phone and copy the one-time password. 6. Enter one-time password in the SMS OTP UI, then select **Verify**. You are now presented with a success page where you can review the flow metadata. :::note Test your integration Before going live with SMS OTP in production, we recommend that you test your integration with an authentication protocol, as explained below. ::: ## Customise SMS service settings When using the Signicat SMS OTP service to send OTP codes to end-users, your integration inherits the SMS settings configured in the Signicat Communication service. On the **Branding** > **Communication** > [**SMS**](https://dashboard.signicat.com/communication/sms) page in the Dashboard, you can manage the SMS settings for your account. In particular, you can customise: - SMS sender name - SMS provider (primary and secondary) Learn more about the SMS settings below or in the [Communication SMS](/docs/dashboard/branding/communication.mdx#sms) documentation. ### Customise SMS sender name A custom SMS sender name lets you unify the user experience with your own brand and products. By changing the sender name, you can display your business name to the recipient of the SMS. By default, the SMS sender name is set to "Signicat". You can change the sender name in one of two ways: - **Global level**: Applies to all SMS messages you send. You change the setting on the [**SMS**](https://dashboard.signicat.com/communication/sms) page in the Signicat Dashboard. For more details, see the [Communication > SMS](/docs/dashboard/branding/communication.mdx#sms) documentation. - **Request level**: Overrides the SMS sender name in a specific authentication flow/request. You pass the SMS sender name as a parameter in the authentication request. When employed, this method has precedence above all other options. Find out how to do this for each protocol in the respective guides below. ### Theming The Signicat Theming services lets you customise your themes to offer a consistent branding experience to your end-users. To customise the theming of the SMS OTP authentication flow, follow the instructions in the [Theming](/docs/dashboard/branding/theming.mdx) documentation. ## Set up a connection with a protocol To establish a connection between Signicat SMS OTP service and your application, you need to integrate with an authentication protocol. With Signicat you can integrate using the following authentication protocols: - [OpenID Connect (OIDC)](/docs/eid-hub/oidc/) - [Security Assertion Markup Language (SAML) 2.0](/docs/eid-hub/saml-2-0/) - [Signicat Authentication REST API](/docs/eid-hub/authentication-api/) See the guides in the [Implement with a protocol](#implement-with-a-protocol) section below for instructions relevant to SMS OTP. :::info Picking a protocol OIDC and SAML 2.0 are official identity protocols. We recommend using OIDC since implementing SAML 2.0 involves more advanced steps. The [Authentication REST API](/apis/eid-hub/) - developed and maintained by Signicat - offers more flexibility and supports _headless_ and _redirect_ integration flow(s) (grant type). You can find integration guides and more information about each protocol in the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ::: ### Implement with a protocol To establish a connection with Signicat SMS OTP, select an implementation guide with an authentication protocol below: * [**Integration with OIDC**](/identity-methods/sms-otp/setup/oidc): Integrate with SMS OTP using OpenID Connect * [**Integration with REST API**](/identity-methods/sms-otp/setup/authentication-api): Integrate with SMS OTP using Signicat Authentication REST API * [**Integration with SAML 2.0**](/identity-methods/sms-otp/setup/authentication-api): Integrate with SMS OTP using SAML 2.0 For more information about the authentication protocols, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ## Advanced security To protect your implementation from fraudulent attacks, make sure you follow the security recommendations in the [Security measures](/identity-methods/sms-otp/setup/security-measures.mdx) page. --- ## Integration guide(8) To integrate with Signicat SMS OTP, you need to: - Set up and configure your account in the Signicat Dashboard. - Choose and implement a connection with an authentication protocol. ## Guides The guides below provide all the steps to help you integrate with SMS OTP. * [**Configure your Signicat account**](/identity-methods/sms-otp/setup/configuration): Configure your account in the Signicat Dashboard * [**Integration with OIDC**](/identity-methods/sms-otp/setup/oidc): Integrate with SMS OTP using OpenID Connect * [**Integration with REST API**](/identity-methods/sms-otp/setup/authentication-api): Integrate with SMS OTP using Signicat Authentication REST API * [**Integration with SAML 2.0**](/identity-methods/sms-otp/setup/authentication-api): Integrate with SMS OTP using SAML 2.0 * [**Security measures**](/identity-methods/sms-otp/setup/security-measures): Protect your implementation from fraud attacks --- ## OpenID Connect(7) This page shows how to integrate with SMS OTP using OpenID Connect (OIDC) as an authentication protocol. ## Before you begin Before starting your OIDC integration with SMS OTP, make sure you have [configured your Signicat account](/identity-methods/sms-otp/setup/configuration/). ## Add an OIDC client To integrate with OIDC, you need to obtain an [OIDC client](/docs/eid-hub/oidc/oidc-client.mdx) and a [secret](/docs/eid-hub/oidc/oidc-client.mdx#how-to-create-a-client-secret) in the Signicat Dashboard. To create a new OIDC client in the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) and select **Create Client**. Configure the following settings: - **Client name**: Name of the client. End-users can view this name in an authentication flow. - **Primary Grant Type**: Grant type (and respective [OIDC authentication flow](/docs/eid-hub/oidc/oidc-implementation.mdx#flows)) you want to use with this client. We strongly recommend **AuthorizationCode**. - **Redirect URI**: URI where end-users are redirected at the end of the flow. It must be HTTPS and an absolute URI. - **Scope**: Controls the attributes returned at the end of an authentication flow. Scopes can differ per eID. :::tip SMS OTP scope For SMS OTP, select the `openid` and `idp-id` scopes. Additionally, you can use the `phone` scope, which returns the same phone number as `idp-id`. ::: For example: OIDC client configuration For more details on how to configure an OIDC client, view the [Set up an OIDC client](/docs/eid-hub/oidc/oidc-client.mdx) guide. #### Add a client secret Depending on the type of your application, you may want to add a client secret. To do this: 1. In the menu for the client, go to the **Secrets** tab and click **Add secret**. 2. Enter a name for your client secret and click **Create**. 3. Copy your new client secret and store it safely. :::warning Important Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one. ::: :::note PKCE Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the [eID and Wallet Hub documentation](/docs/eid-hub/oidc/advanced-security/proof-key-for-code-exchange-pkce.mdx). ::: ## OIDC implementation In OIDC, an application first needs to specify which permissions to request, then send the end-user to a browser to get their permission. After the end-user approves the authentication request and gets redirected to your website, your application receives back an authorisation code. You exchange the authorisations code for an access token and an ID token, where you can find the end-user personal information. #### Example of authentication request To begin the authorization flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with SMS OTP. In OIDC, the `authorize` endpoint performs the authentication of the end-user. It directs the end-user to the authorisation server, where the end-user enters their mobile number to receive an SMS with a one-time token. The authorization URL corresponds to a webpage where the authentication flow begins. Here is how to build an authentication URL: ```bash https:///auth/open/connect/authorize? &client_id=OIDC_CLIENT_ID &response_type=GRANT_TYPE_CODE &redirect_uri=REDIRECT_URI &scope=OIDC_SCOPES &ui_locales=LANGUAGE_TAG &state=STATE ``` The authentication URL consist of two parts: - The base URL `https:///auth/open/connect/authorize` where `SIGNICAT_ACCOUNT_DOMAIN` is the [domain](/docs/dashboard/glossary.mdx#signicat-domain) configured in your Signicat account. - The query parameters: - `client_id`: The client ID of your OIDC application that you created in the Dashboard. - `redirect_uri`: The URI where the end-user is redirected to at the end of the authentication flow. This must be an absolute URI using the HTTPS protocol. - `response_type`: Specifies the desired grant type for the OIDC flow. - `state`: A randomly generated string used to maintain the state between the request and the callback. It helps mitigate CSRF attacks by ensuring the returned value matches the one sent in the initial request. - `scope`: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow. For SMS OTP, use `openid`, `idp-id` and optionally `phone`. - `ui_locales`: (ISO 639-1 code) sets the language in the UI. By default, the language is English. For an overview of the languages supported, see the [UI language](/identity-methods/sms-otp/code-examples/#ui-language) page. :::tip Matching configuration The query parameters in the URL must match the configuration of your OIDC client in the Dashboard. ::: Here is an example authentication URL for an authorization code flow: ```bash https://example.sandbox.signicat.com/auth/open/connect/authorize? &client_id=dev-test-client-123 &response_type=code &redirect_uri=https://example.com/callback &scope=openid%20idp-id%20phone &ui_locales=en &state=1713343316409-zie ``` #### Example of user journey When end-users access the authentication URL, the user journey looks like this: #### Set the UI language To change the language on the SMS OTP UI, use the query string parameter `ui_locales` in the OIDC authorization request. For example, use `ui_locales=el` to set the SMS OTP UI to Greek. :::info Default language By default, the UI language is English. ::: For an overview of the languages supported, see the [UI language](/identity-methods/sms-otp/code-examples/#ui-language) page. #### Prefill user information You can use the `login_hint` query parameter to prefill the phone number of the end-user, so that the end-user does not have to enter this information manually when authenticating. For example, you can specify a phone number in the authentication URL with `login_hint=mobile:%2B447700900000` : ```bash {6} https://example.sandbox.signicat.com/auth/open/connect/authorize? &client_id=dev-test-client-123 &response_type=code &redirect_uri=https://example.com/callback &scope=openid%20idp-id%20phone &login_hint=mobile:%2B447700900000 ``` This will display the phone number to the end-user when they start the authentication flow. To learn more about data prefilling, see the [Prefilling user information](/docs/eid-hub/concepts/prefilling-information/) conceptual guide. :::warning `login_hint` field format Note that the phone number format must be `%2B`. For example, use the URL encoded (percent encoding) `%2B447700900000` string to represent the `+44 7700900000` phone number. ::: #### ACR values In OIDC, `acr_values` are a space-separated list of key-value pairs to customise the authentication flow. Signicat defined a set of custom keys that help you control specific features of an authentication flow. ##### Customise SMS sender name To override the SMS sender name displayed to the recipient on a request basis, use `otp_sms_sender:YOUR_SENDER_NAME`. The value cannot contain spaces; use a double underscore instead. For example `otp_sms_sender:Signicat__AS`, displays "Signicat AS" as the SMS sender name. Example of an authorization request with `acr_values`: ```bash {6} https://example.sandbox.signicat.com/auth/open/connect/authorize? &client_id=dev-test-client-123 &response_type=code &redirect_uri=https://example.com/callback &scope=openid%20idp-id%20phone &acr_values=idp:otp-sms%20otp_sms_sender:Signi__Kitten ``` ##### IdP scoping To automatically redirect the end-user to SMS OTP, thus skipping the eIDs selection screen, use `idp:otp-sms`. This prevents users from choosing other eIDs that may be active in your account. ## Advanced security To protect your implementation from fraudulent attacks, make sure you follow the security recommendations in the [Security measures](/identity-methods/sms-otp/setup/security-measures.mdx) page. ## Next steps Continue your journey with more SMS OTP guides: * [**Attributes reference**](/identity-methods/sms-otp/code-examples/): Scopes and claims for SMS OTP with OIDC Dive deeper into OIDC and improve your application with advanced security features: * [**Advanced OIDC implementation**](/docs/eid-hub/oidc/oidc-implementation): Learn about available flows, endpoints, claims, key rotation, security, error codes and more. * [**Code examples**](/docs/eid-hub/oidc/code-examples/): Follow along a code example with OIDC --- ## SAML 2.0(Setup) Get started with the SAML 2.0 integration with our guides: * [**SAML 2.0**](/docs/eid-hub/saml-2-0/): Find out more about SAML, an XML-based standard for authentication. * [**Set up a SAML connection**](/docs/eid-hub/saml-2-0/saml-metadata): Exchange metadata to set up a SAML connection with Signicat. See what SAML parameters apply SMS OTP: * [**Attributes reference**](/identity-methods/sms-otp/code-examples/): Attributes and examples for SMS OTP with SAML 2.0 --- ## Security measures Attackers can try to exploit your SMS OTP integration in multiple ways. When your implementation is not secured appropriately, malicious actors can target and profit from your web forms with SMS OTP by targeting your SMS messaging channels. An example of a common exploitation is SMS pumping, a type of fraud attack in which malicious actors trigger high SMS traffic towards paid providers thus profiting from your infrastructure and making your organisation incur in additional costs. To protect your integration and mitigate the risks of fraudulent behaviours, make sure that you implement the security measures described on this page. :::note Important The information in this page is for guidance only. Note that this is not a complete list of all security measures you should take, and should not be taken as definitive advice. ::: ### Recommended actions The most important secure practices are to: - Restrict sending SMS messages to countries outside of target markets. - Rate limit sending to countries outside of target markets. - Implement a sophisticated CAPTCHA. For example, reCAPTCHA. - Perform a manual or automatic review of SMS statistics per country. - Apply counter measures to all processes that include SMS processes, such as registration, login, update user data, opt-out and more. Note that you should apply these measures to your web forms or any other service on your side of the implementation. ### Measures known to be circumvented by attackers Malicious actors may design their attacks to circumvent the security mitigations you put in place. Below, you can find known cases of measures that have proven ineffective: - Limiting the number of requests per IP address. - Attackers use bot nets to utilise many different IPs. - Blocking IPs or IP ranges. - Attackers use bot nets to utilise many different IPs. - Blocking multiple SMS to the same MSISDN. - Attackers generate many random MSISDNs. - Blocking SMS to many different MSISDNs from one IP address. - Attackers circle different MSISDNs through different IPs. - Using simple CAPTCHA solutions. - Attackers use text recognition or cheap labour to solve CAPTCHA. - Watching out for a high number of undelivered messages per country. - Attackers return fake DLR (Delivery Report). Though the above measures have proven ineffective, you should prioritise fixing any identified vulnerabilities and follow the best security practices. --- ## Public System for Digital Identity (SPID) {/* markdownlint-disable-next-line */} ## About SPID :::tip What is SPID? If you are new to SPID, you can learn more about how SPID works on this page. ::: The Public System for Digital Identity (SPID; from Italian "Sistema Pubblico di Identità Digitale") is an Italian electronic identity scheme that allows Italian citizens to access the digital services of: - The Italian public administration. - Private companies or traders that require it as an log-in method. - Member states of the European Union part of the Italian [eIDAS node](https://www.eid.gov.it/abilita-eidas.html). SPID is a notified [eIDAS](https://ec.europa.eu/digital-building-blocks/wikis/display/EIDCOMMUNITY/Italy+-+SPID) scheme with three [levels of assurance](#levels-of-assurance-loa). SPID is regulated and administered by the [Agency for Digital Italy](https://www.agid.gov.it/en/agency/about-us) (AgID), the technical agency of the Italian Presidency of the Council of Ministers. ## Who uses SPID Italian citizens over 18 years old and with a valid Italian identity document can apply for SPID at one, or more, of the accredited [Digital Identity Providers (IdP)](https://www.spid.gov.it/en/what-is-spid/how-to-choose-between-digital-identity-providers/). These are private companies accredited by AgID to provide digital identities and manage user authentication according to the rules issued by the Agency. Digital identity providers issue SPID credentials, together with any additional security solutions (OTP via SMS or app) necessary to authenticate with a higher level of assurance. When identifying online, users select their IdP from a list displayed after pressing the mandatory "Entra con SPID" (“Login with SPID”) button. Users authenticate with their credentials on the portal of the IdP of their choice. ## Roles in the SPID scheme The SPID ecosystem consists of different roles: - **Digital identity provider** (or IdP), private entities authorised by AgID for the creation and management of users' digital identities. - **Service providers** (or SP), public or private organizations, which by enabling access to their online services through digital identity allow fast, safe and secure use of services. - **Users** (citizens and businesses) who have their own digital identity, certified by one or more IdPs, to access the online services of the public administration and private websites. - **Aggregators** are organisations that offer service providers, aggregated by them, the possibility to make their services accessible through SPID without having to integrate to SPID independently. :::tip Signicat as Aggregator Signicat is a private **Aggregator** of SPID, and acts as a message broker between the identity provider and the service provider. Customers, that integrate SPID in their services through Signicat, are referred to as **Service Providers** in the SPID scheme. ::: ## Levels of Assurance (LoA) [Level of Assurance](/docs/dashboard/glossary.mdx#level-of-assurance-loa) refers to the degree of confidence in the claimed identity of a person. A higher level of assurance reduces the risks and ensures a more secure transaction. SPID provides three levels of assurance: - **Level 1** (Low) allows access to online services through the SPID credentials (username and password). - **Level 2** (Substantial) is necessary for services that require a higher degree of security. Level 2 allows access through SPID level 1 credentials and the generation of a temporary OTP (one-time password) access code or the use of an app that can be used through a device, such as a smartphone or a tablet. - **Level 3** (High) provides, in addition to the SPID level 1 credentials, the use of additional security solutions and any physical devices, like smart cards, that are supplied by the identity provider. :::note LoA levels in the eIDAS Regulation The [eIDAS Regulation](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eIDAS+Levels+of+Assurance) has established three levels of assurance for electronic identification: - Low - Substantial - High where "high" is the highest level of assurance. Learn more about the eIDAS definition of LoA in the [EU documentation](https://ec.europa.eu/digital-building-blocks/wikis/display/CEFDIGITAL/eIDAS+Levels+of+Assurance). ::: ## SPID Flows ### Data categories The SPID ecosystem distinguishes between two categories of end-user data: - **Personal data**: Includes attributes such as an individual's name, date of birth or national identity number. - **Extra personal (or secondary) data**: Extends access to secondary information such as email, phone number or home address. :::tip Learn more For an overview of the attributes that belong to each category, see the [scopes and claims for OIDC](/identity-methods/spid/code-examples.mdx#oidc-scopes-and-claims) table. ::: ### Flows SPID flows define and restrict access to an individual's personal data by matching specific data categories. You can find what flows are available in the table below: :::CustomTable{columnWidths="25% 25% 50%"} | Flow | Data category | Information | |---------------|----------------|-------------| | **Authentication flow** | Personal data | Provides basic personal attributes such as an individual's name, date of birth or national identity number. | | **Registration flow** | Personal data Extra personal data | All personal attributes available through SPID. | ::: When identifying online, end-users give their consent to share specific data attributes with third parties. The data they share with you depend on the flow you integrate in your authentication flow. :::info How to integrate with a specific flow? You can set up both Authentication and Registration flows when [setting up SPID with OIDC](/identity-methods/spid/setup.mdx#integrate-with-an-authentication-protocol). ::: ## SAML metadata The SPID system relies on the SAML 2.0 protocol. You can see an example of metadata used by SPID [here](https://demo.spid.gov.it/metadata.xml). :::info How SAML works SAML is an authentication protocol that uses metadata (XML-based documents) to exchange information between entities, like a service provider and an identity provider. A metadata file contains an X509 certificate, endpoints and other information needed to communicate with another entity. ::: Metadata is hosted and made publicly available on the service provider domain. In the case of SPID, AgID handles the registration of metadata for new service providers that join the SPID federation. Then, AgID is responsible for sharing the metadata with the identity providers. As a customer, you receive a metadata file with information about your organisation when [applying for SPID integration with Signicat](/identity-methods/spid/prerequisites.mdx#spid-metadata). --- ## Authentication Api :::note Documentation coming soon Our documentation to integrate with SPID using the Authentication REST API is coming soon. To learn more, you can contact us by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: For more information about the different protocol types, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. You can view examples of responses and the attributes to use in your request in the [Attributes reference](/identity-methods/spid/code-examples.mdx) page. --- ## Attributes reference(Spid) You use SPID to verify the identity of end-users and obtain relevant personal information. This page shows what end-user information you can request and receive for the following authentication protocols: - [OpenID Connect (OIDC)](#oidc-scopes-and-claims) - [Signicat Authentication REST API](#signicat-authentication-rest-api-attributes) ## OIDC scopes and claims You can use the following OIDC scopes to request personal information from an end-user using SPID. The claims column shows the data fields returned in the response. :::tip Include claims in ID token By default, all claims listed below are returned in the [**UserInfo**](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. In addition, you can configure which user data claims you want to receive in the **ID token** object. To set this up, go to the **Products** > **eID and Wallet Hub** > [**OIDC Clients**](https://dashboard.signicat.com/oidc-clients/) page in the Dashboard, choose your client, and edit the claims under **Advanced Security > ID Token User data**. ::: :::CustomTable | Scope | Claim | Example | Description | SPID data category | | :----------- | :----------------------- | :-------------- | :------------- | :--------------------- | | `spid` | `birthdate` | 1985-12-10 | The date of birth of the user (format `YYYY-MM-DD`). | Personal data | | `spid` | `family_name` | Lovelace | The surname of the user. | Personal data | | `spid` | `gender` | F | The biological sex of the user (`M` or `F`). | Personal data | | `spid` | `given_name` | Ada | The first name of the user. | Personal data | | `spid` | `idp_id` | ABCD-123456789A | The IdP (SPID) code of the user. Format is ` ` where `code_IdP` is a four characters code unique for the identity provider. | Personal data | | `spid` | `organisation` | | The registered name of a company. For example, `Agenzia per l'Italia Digitale`. | Personal data | | `spid` | `spid_company_fiscal_number` | TINIT-LVLDAA85T50G702B | The fiscal code of the legal person (`TINIT-`). | Personal data | | `spid` | `spid_county_of_birth` | PI | The county (province) of birth of the user. For example, `MI` for the county of Milan. Returns `EE` for citizens born abroad. | Personal data | | `spid` | `spid_id_card` | passaporto KK1234567 questuraLivorno 2016-09-04 2026-09-03 | The information on the identity document of the user. A single-spaced concatenated string with format: ` `, where: `document_type` is the type of document. Accepted values are `cartaIdentita`, `passaporto`, `patenteGuida`, `patenteNautica`, `librettoPensione`, `patentinoImpTermici`, `portoArmi`, `tesseraRiconoscimento`. `document_number` is the document number. `issuer` is a concatenated string containing the major parts of the name of the issuing entity. For example, `provinciaCatania` (Provincia di Catania). `issue_date` is the document issue date in YYYY-MM-DD format. `expiration_date` is the document expiration date in YYYY-MM-DD format. | Personal data | | `spid` | `spid_iva_code` | | The VAT identification number of a company. Format: `VATIT-`. | Personal data | | `spid` | `spid_place_of_birth` | G702 | The place of birth of the user. A string corresponding to the *codice Belfiore* of the municipality or foreign country. For example, `F205` for the city of Milan. | Personal data | | `spid` | `spid_registered_office` | Via Listz 21 00144 Roma | The registered address of a company. | Personal data | | `nin` | `nin` | TINIT-LVLDAA85T50G702B | The national identity number (“Codice Fiscale”/ Fiscal Code) of the user. This is the same as `fiscalNumber`. Format is `TINIT-`. | Personal data | | `nin` | `nin_type` | TAX | The type of national identity number. Always `TAX` for SPID. | Personal data | | `nin` | `nin_issuing_country` | IT | The issuing country of the national identity. Always `IT` for SPID. | Personal data | | `spid-extra` | `address` | `{`` "formatted": "Via Listz 21, Roma, RM, 00144, IT",`` "street_address": "Via Listz 21",`` "locality": "Roma",`` "region": "RM",`` "postal_code": "00144",`` "country": "IT"``}` | The residential address of the user. `"formatted"` is obtained by concatenating multiple attributes with format: `domicileStreetAddress, domicileMunicipality, domicileProvince, domicilePostalCode, domicileNation`, where: `domicileStreetAddress` is composed of: `type`: via, viale, piazza `street name` `house nr` (or "Nr. civico") `domicileMunicipality` is the name of the municipality (or "Comune") `domicileProvince` is the 2-characters province or county code. Returned separately as `region` `domicilePostalCode` is the 5-digit long postal code (or "CAP") `domicileNation` is the 2-characters country code | Extra personal data | | `spid-extra` | `email` | aabyron@hotmail.com | The email address of the user. | Extra personal data | | `spid-extra` | `phone_number` | 3939393939 | The phone number of the user. | Extra personal data | | `spid-extra` | `spid_digital_address` | | PEC (Posta Elettronica Certificata/Certified email address) address. | Extra personal data | | `spid-extra` | `spid_expiration_date` | 02/02/2018 00:00:00 | Identity document expiration date. Format is `DD/MM/YYYY HH:MM:SS`. | Extra personal data | ::: :::note SPID attributes table For further details about attributes and data formats, see the official SPID [documentation](https://www.agid.gov.it//sites/default/files/repository_files/regole_tecniche/tabella_attributi_idp_v1_0.pdf). ::: ### OIDC response example Below, you find examples of responses returned from an identity verification flow with SPID. This section shows response examples for the [UserInfo](/docs/eid-hub/oidc/oidc-implementation.mdx#userinfo) endpoint. #### Example of natural person Examples for the [test user](https://demo.spid.gov.it/users) *Ada Lovelace*: Scopes in the request: `spid`. ```json { "idp_id": "SPID-002", "spid_place_of_birth": "G702", "spid_county_of_birth": "PI", "spid_id_card": "passaporto KK1234567 questuraLivorno 2016-09-04 2026-09-03", "given_name": "Ada", "family_name": "Lovelace", "birthdate": "1985-12-10", "gender": "F", "sub": "HIDhYNt8ZaSa8dtg-hrljCnhiMXYhF54gFudp-warQM=", "idp_issuer": "https://demo.spid.gov.it" } ``` Scopes in the request: `spid`, `nin`, `spid-extra`. ```json { "idp_id": "SPID-0020020020", "nin": "TINIT-LVLDAA85T50G702B", "nin_type": "TAX", "nin_issuing_country": "IT", "spid_place_of_birth": "G702", "spid_county_of_birth": "PI", "spid_id_card": "passaporto KK1234567 questuraLivorno 2016-09-04 2026-09-03", "given_name": "Ada", "family_name": "Lovelace", "birthdate": "1985-12-10", "gender": "F", "phone_number": "3939393939", "spid_expiration_date": "02/02/2018 00:00:00", "address": { "formatted": "Via Listz 21, Roma, RM, 00144, IT", "street_address": "Via Listz 21", "locality": "Roma", "region" : "RM", "postal_code": "00144", "country": "IT" }, "email": "aabyron@hotmail.com", "sub": "HIDhYNt8ZaSa8dtg-hrljCnhiMXYhF54gFudp-warQM=", "idp_issuer": "https://demo.spid.gov.it" } ``` #### Example of organisation Example of a response containing the `organisation` claim: ```json { "spid_place_of_birth": "Roma", "spid_county_of_birth": "RM", "organisation": "Agenzia per l'Italia Digitale", "spid_registered_office": "Via Listz 21 00144 Roma", "spid_company_fiscal_number": "TINIT-GDASDV00A01H501J", "spid_iva_code": "VATIT-97735020584", "spid_id_card": "CartaIdentità AA00000000 ComuneRoma 2018-01-01 2028-01-01", "given_name": "SpidValidator", "family_name": "AgID", "birthdate": "2000-01-01", "gender": "M", "phone_number": "+393331234567", "spid_digital_address": "pec@pecagid.gov.it", "spid_expiration_date": "2028-01-01", "address": { "formatted": "Via Listz 21, Roma, RM, 00144, IT", "street_address": "Via Listz 21", "locality": "Roma", "region" : "RM", "postal_code": "00144", "country": "IT" }, "email": "spid.tech@agid.gov.it", "sub": "ZZ0eRjWltcKswng6W-6....y-DDc1AwSEUP7C2aMZtw=", "sub_legacy": "z507Ae7ecG282uDCSHiYa1Evt-Ryvq0ymKJqcdnzcTk=", "idp_issuer": "https://demo.spid.gov.it/validator " } ``` ## Signicat Authentication REST API attributes The Signicat Authentication REST API supports the following request attributes for SPID: :::CustomTable{minTableSize="900px" columnWidths="20% 20% 40% 20%"} | Attribute | Example (response) | Description | SPID data category | | :-------------------- | ------------------ | :------------------ | :---------------------- | | `companyFiscalNumber` | TINIT-LVLDAA85T50G702B | The fiscal code of the legal person (`TINIT-`). | Personal data | | `countryOfBirth` | PI | The county (province) of birth of the user. For example, `MI` for the county of Milan. Returns `EE` for citizens born abroad. | Personal data | | `dateOfBirth` | 1985-12-10 | The date of birth of the user (format `YYYY-MM-DD`). | Personal data | | `firstName` | Lovelace | The surname of the user. | Personal data | | `gender` | F | The biological sex of the user (`M` or `F`). | Personal data | | `idCard` | passaporto KK1234567 questuraLivorno 2016-09-04 2026-09-03 | The information on the identity document of the user. A single-spaced concatenated string with format: ` `, where: `document_type` is the type of document. Accepted values are `cartaIdentita`, `passaporto`, `patenteGuida`, `patenteNautica`, `librettoPensione`, `patentinoImpTermici`, `portoArmi`, `tesseraRiconoscimento`. `document_number` is the document number. `issuer` is a concatenated string containing the major parts of the name of the issuing entity. For example, `provinciaCatania` (Provincia di Catania). `issue_date` is the document issue date in YYYY-MM-DD format. `expiration_date` is the document expiration date in YYYY-MM-DD format. | Personal data | | `ivaCode` | | The VAT identification number of a company. Format: `VATIT-`. | Personal data | | `lastName` | Lovelace | The surname of the user. | Personal data | | `name` | Ada Lovelace | The (composite ` `) full name of the user. | Personal data | | `nin` | `{`` "value": "TINIT-BRGLRZ80D58H501Q",`` "issuingCountry": "IT",`` "type": "TAX"``}` | National identity number object, where: `value`: The national identity number (“Codice Fiscale”/ Fiscal Code) of the user. Format is `TINIT-`. `issuingCountry`: The issuing country of the national identity. Always `IT` for SPID. `type`: The type of national identity number. Always `TAX` for SPID. | Personal data | | `organisationName` | | The registered name of a company. For example, `Agenzia per l'Italia Digitale`. | Personal data | | `placeOfBirth` | G702 | The place of birth of the user. A string corresponding to the *codice Belfiore* of the municipality or foreign country. For example, `F205` for the city of Milan. | Personal data | | `registeredOffice` | Via Listz 21 00144 Roma | The registered address of a company. | Personal data | | `address` | Via Listz 21, Roma, RM, 00144, IT | The residential address of the user obtained by concatenating multiple attributes with format: `Street, City, Region, PostalCode, Country`, where: `Street` is composed of: `type`: via, viale, piazza `street name` `house nr` (or "Nr. civico") `City` is the name of the municipality (or "Comune") `Region` is the 2-characters province code `PostalCode` is the 5-digit long postal code (or "CAP") `Country` is the country code **Note**: This also returns an additional object (`addressFormatted`) where all the above variables are explicit fields. | Extra personal data | | `digitalAddress` | | PEC (Posta Elettronica Certificata/Certified email address) address. | Extra personal data | | `email` | aabyron@hotmail.com | The email address of the user. | Extra personal data | | `expirationDate` | 02/02/2018 00:00:00 | Identity document expiration date. Format is `DD/MM/YYYY HH:MM:SS`. | Extra personal data | | `phoneNumber` | 3939393939 | The phone number of the user. | Extra personal data | ::: :::note SPID code in idpId The Authentication REST API returns `idpId` by default. You do not need to specify this attribute in your request. `idpId` returns the SPID code of the user. Format is ` ` where `code_IdP` is a four characters code unique for the identity provider. An example is `ABCD-123456789A`. ::: #### Authentication API request example To create a session using the Authentication REST API, you send a POST request to the [Create a new session](pathname:///apis/eid-hub/#tag/Authentication-Session/operation/CreateSession) endpoint of the Authentication REST API. This is `https://api.signicat.com/auth/rest/sessions`. You define the parameters of the session in the payload of the request. For example: ```json { "allowedProviders": [ "spid" ], "flow": "redirect", "requestedAttributes": [ "address", "companyFiscalNumber", "countryOfBirth", "dateOfBirth", "digitalAddress", "email", "expirationDate", "firstName", "gender", "idCard", "ivaCode", "lastName", "name", "nin", "organisationName", "phoneNumber", "placeOfBirth", "registeredOffice" ], "callbackUrls": { "success": "https://example.com/success", "abort": "https://example.com/abort", "error": "https://example.com/error" } } ``` #### Authentication API response example Example for the [test user](https://demo.spid.gov.it/users) *Lucrezia Borgia*. Response object (`subject` field): ```json { "id": "51F6wWfm0jAIHYtoJpAViZ3cKp-Q3t9i2ZfmR0YHgHs=", "idpId": "SPID-004", "name": "Lucrezia Borgia", "firstName": "Lucrezia", "lastName": "Borgia", "dateOfBirth": "1980-04-18", "email": "luborgia@msn.com", "nin": { "value": "TINIT-BRGLRZ80D58H501Q", "issuingCountry": "IT", "type": "TAX" }, "placeOfBirth": "H501", "organisationName": "", "registeredOffice": "", "companyFiscalNumber": "", "ivaCode": "", "idCard": "cartaIdentita AK987654 comuneFerrara 2012-11-28 2023-04-18", "digitalAddress": "", "expirationDate": "2019-01-01", "phoneNumber": "3495555555", "gender": "F", "address": "Via Listz 21, Roma, RM, 00144, IT", "addressFormatted": { "FullAddress": "Via Listz 21, Roma, RM, 00144, IT", "Street": "Via Listz 21", "City": "Roma", "Region": "RM", "PostalCode": "00144", "Country": "IT" } } ``` --- ## SPID The Public Digital Identity System (SPID; from Italian "Sistema Pubblico di Identità Digitale") is an electronic identity scheme in Italy that can be used for identity verification, authentication and data enrichment. If you want to read more high-level documentation about SPID before you start the integration, see [About SPID](/identity-methods/spid/about-spid.mdx#about-spid) and [Use cases](/identity-methods/spid/use-cases.mdx). ## Get started * [**Setup of SPID**](/identity-methods/spid/setup): Select eID and control the flow * [**Attributes reference**](/identity-methods/spid/code-examples): See response code examples and parameter descriptions * [**Sign agreements and metadata**](/identity-methods/spid/prerequisites) * [**Test information**](/identity-methods/spid/test): View test users in the SPID demo environment ## Tell me more * [**About SPID**](/identity-methods/spid/about-spid): High-level information about SPID * [**Use cases**](/identity-methods/spid/use-cases): High-level description of how SPID works in a usage context ## Support If you have questions, you can contact us by creating a support ticket in the Signicat Dashboard: [**Create support ticket**](https://dashboard.signicat.com/contact-us/tickets/new) --- ## Sign agreements and metadata Before you [set up](/identity-methods/spid/setup.mdx) SPID in production, you must sign an agreement with Signicat and obtain access to our infrastructure. During onboarding, Signicat registers your organisation in the SPID federation. ## Prerequisites To prepare the contract, you need to provide us with the following information: :::note Information about your organisation - Contact information: name, email and phone number. - VAT identification number. - Fiscal code (_Codice Fiscale_), if your organisation is also registered in Italy. - Contact information of the employees who have permission to revoke or block SPID. - The title to display on the SPID client. For example: your company name. ::: :::info Signicat customers If your are an existing customer, you need to apply for an addendum to your existing Signicat contract. For new customers, the addendum is already included in the initial agreement. ::: ## Sign an agreement with Signicat Signicat Sales team can provide further information about the administrative steps required to implement the SPID solution successfully. To get started with this, please contact the [Signicat Sales](https://www.signicat.com/contact/contact-sales) department. ## SPID Metadata Signicat helps you with registering you as a new customers in the SPID federation by submitting [SAML metadata](/identity-methods/spid/about-spid.mdx#saml-metadata). ### SAML Metadata When you integrate SPID through Signicat, a metadata document with information about your organisation is generated and registered with [AgID](https://www.agid.gov.it/en/agency/about-us) (the agency that regulates SPID). Note that AgID processes metadata submissions for new service providers three times a week. :::tip Processing times It may take up to three working days to complete metadata registration before you can start using SPID. To receive updates on the status of your application, please contact us. [**Contact an expert**](https://www.signicat.com/contact/contact-sales) ::: :::note SPID metadata needs to be updated for new domains If you add a new domain in the Signicat Dashboard and want to connect your SPID integration to that domain, the SPID metadata with AgID needs to be updated so that SPID can work correctly on the new domain. If you update your domain in the Signicat Dashboard, please ask our support team to update your SPID metadata with AgID by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: #### Installation in production After your initial contact with Signicat, an onboarding manager will be assigned as technical responsible in the SPID agreement. They will handle communication with AgID and your organisation. When the metadata is approved, it will be available in your Signicat Dashboard account. #### Installation in sandbox account When testing SPID in a [sandbox account](/docs/dashboard/glossary.mdx#sandbox), you can verify your metadata and installation by using [test users](/identity-methods/spid/test.mdx). :::tip Testing SPID To test SPID in your sandbox account, see the [Try out SPID](/identity-methods/spid/test.mdx) documentation. ::: --- ## Set up SPID This page describes the process of setting up a SPID implementation through the Signicat eID and Wallet Hub. :::info SPID is part of the eID and Wallet Hub For general information about integrating with Signicat eIDs, see the **eID and Wallet Hub** [documentation](/docs/eid-hub/). ::: ## Initial preparations If you do not have an account already, then you need to sign up to the Signicat Dashboard for free and complete the initial preparations. To do this: 1. Sign up to the [Signicat Dashboard](https://login.signicat.com/ownidp/web/registration) and register your profile. 2. Ensure that you have created an [organisation](/docs/dashboard/organisation-management/organisations.mdx). 3. Create an [account](/docs/dashboard/organisation-management/accounts.mdx). To do this: 1. Go to **Signicat Dashboard** > [**Organisation**](https://dashboard.signicat.com/org-mgmt/), then select **+ Add account**. 2. Enter an account name, choose the type of account that you want to create, then select **Create**. 4. Create a [domain](/docs/dashboard/organisation-management/domains/). To do this: 1. Go to **Signicat Dashboard** > **Settings** > [**Domains**](https://dashboard.signicat.com/domains/), then select **+ Add domain**. 2. To create a standard domain, enter a domain name. Then, select **Add domain**. 3. To create a custom domain, follow the instructions in the [Custom domains](/docs/dashboard/organisation-management/domains/custom/) documentation. :::tip Account types We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately. ::: ## Add SPID :::warning Production environments You can always test SPID in a sandbox account, but you need to complete some preparations to go live in production. To go live in production, you need to configure access to SPID with an onboarding manager. To do this, follow the steps in [Sign agreements and metadata](/identity-methods/spid/prerequisites.mdx) or [contact us](https://www.signicat.com/contact/contact-sales). ::: When you are ready to start the setup, you need to add SPID to the list of supported eIDs in the Signicat Dashboard. To do this: 1. Go to **Dashboard** > **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **+ Add new** in the top right. 3. Choose **Sistema Pubblico di Identità Digitale** from the list of available eIDs. 4. In the SPID configuration page, enter the following about your organisation: - **VAT number**: The VAT tax number. In sandbox, you may enter any value. - **Fiscal code** (_Codice Fiscale_): Optional. Applies only if your organisation is (also) registered in Italy. 5. Select **Add** to add SPID to your active eIDs. You have just configured SPID in the Signicat Dashboard. SPID should now be available in your list of active eIDs. After you activate SPID, you need to set up a connection with an authentication protocol, such as OIDC, SAML 2.0 or the Signicat Authentication API. Find out how to do this in the [Integrate with an authentication protocol](#integrate-with-an-authentication-protocol) section. ## Try out SPID with test users To try out SPID in a sandbox environment, learn more in the [Test SPID](/identity-methods/spid/test/) page. :::note Note You can test SPID authentications before you integrate with a protocol. ::: ## Integrate with an authentication protocol You need to set up an authentication protocol to integrate with SPID through Signicat. OIDC and SAML 2.0 are official identity protocols, while the Authentication REST API is a solution developed and maintained by Signicat. We recommend using OIDC, since SAML 2.0 is much more complex to implement on your side and usually requires a federation agent already in place. For more information about the different protocol types, see the [Signicat eID and Wallet Hub](/docs/eid-hub/) documentation. ### Integration guide with OIDC * [**Integration guide with OIDC**](/identity-methods/spid/spid-oidc-setup): Integrate with SPID using OpenID Connect ### Integration guide with SAML 2.0 To get started with SAML 2.0, refer to the [eID and Wallet Hub - SAML 2.0](/docs/eid-hub/saml-2-0/saml-metadata.mdx) page. ### Integration guide with the Authentication REST API To get started with the Authentication REST API, refer to the following guides: - [API reference](/apis/eid-hub/) - [API overview](/docs/eid-hub/authentication-api/) ## Troubleshooting :::info Using SPID with new domains If you add a new domain in the Signicat Dashboard and want to connect your SPID integration to that domain, the SPID metadata with AgID needs to be updated so that SPID can work correctly on the new domain. If you update your domain in the Signicat Dashboard, please ask our support team to update your SPID metadata with AgID by [creating a support ticket](https://dashboard.signicat.com/contact-us/tickets/new) in the Signicat Dashboard. ::: --- ## Integration guide with OIDC This page describes how to integrate with SPID using the OpenID Connect (OIDC). ## Prerequisites To integrate using OIDC, you must to configure: - An [OIDC client](/docs/eid-hub/oidc/oidc-client.mdx). - An [OIDC secret](/docs/eid-hub/oidc/oidc-client.mdx#how-to-create-a-client-secret). Learn how to do this in the eID and Wallet Hub [Quick start guide](/docs/eid-hub/quick-start/). ## SPID Flows SPID is designed to provide alternative flows to meet your business needs. [SPID flows](/identity-methods/spid/about-spid.mdx#spid-flows) determine the attributes of an individual's data that a service provider can retrieve. Signicat matches the different SPID flow with different configuration options. This section describes how to control those flow options when using the OIDC protocol. You can control the SPID flow by choosing the `scope` parameter connected to the OIDC client: :::CustomTable{columnWidths="25% 25% 50%"} | Scopes | SPID Flow | Description | | :----------------- | --------------------- | :----------------------------------------------------------- | | `spid`, `nin` | SPID Authentication Flow | Using these you collect **Personal data** from the SPID identity provider. The end-user will be asked for consent. | | `spid`, `nin`, `spid-extra` | SPID Registration Flow | Using these you collect both **Personal data and Extra personal data**, such as email, mobile number and address, from the SPID identity provider. The end-user will be asked for consent. | ::: For an overview of the attributes that belong to each scope, see the [scopes and claims for OIDC](/identity-methods/spid/code-examples.mdx#oidc-scopes-and-claims) table. ### Scopes To associate a specific `scope` with your OIDC client: 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**OIDC clients**](https://dashboard.signicat.com/oidc-clients/) and select the OIDC client you configured for SPID. 2. Select **Edit** to view your client configuration. 3. Navigate to the **Access** tab. 4. In the "Allowed scopes" section, add the SPID scopes. You can choose between: - `openid` (required) - `nin` - `spid` - `spid-extra` 5. Select **Update** to save your changes. ## Example of authentication Here is an example authentication URL: ```bash https://test.sandbox.signicat.example/auth/open/connect/authorize? &client_id=dev-test-client-123 &response_type=code &scope=openid%20nin%20spid &redirect_uri=https://myservice.example/redirect &state=1599045135410-jFe &prompt=login ``` The URL consists of a base URL `https:///auth/open/connect/authorize` and the parameters: - `client_id`: OIDC Client ID you created on Dashboard. - `scope`: OIDC scopes that determine the SPID flow. `openid` is a required parameter. :::info SPID scopes SPID supports the following scopes: `spid`, `nin`, `spid-extra`. You can find a complete overview in the [Attributes reference](/identity-methods/spid/code-examples.mdx) page. ::: - `redirect_uri`: the URI where the end-user is redirected to at the end of the authentication flow. - `response_type`: based on the response flow you set for the OIDC Client (this is an advanced feature). You can view examples of responses and explore the scopes and claims in the [Attributes reference](/identity-methods/spid/code-examples.mdx) page. --- ## Try out SPID In your sandbox account, you can test an authentication with the SPID Test environment. ## Test SPID Below, you can find instructions on how to run a test authentication with SPID. :::note Prerequisites Make sure SPID is active in your account. Learn more in [Add SPID](/identity-methods/spid/setup.mdx#add-spid). ::: ### Discover your metadata URL When you activate SPID, a [SAML metadata](/identity-methods/spid/about-spid.mdx#saml-metadata) document gets generated and associated to your domain automatically. The metadata is available at the following URL: `https:///idps/spid/metadata`. For example, if your sandbox domain is `https://spidating.sandbox.signicat.com`, your metadata URL is `https://spidating.sandbox.signicat.com/idps/spid/metadata`. ### Register your metadata URL To test authentications through the official SPID demo environment, you need to register your metadata URL on the SPID demo validator website. To do this: 1. Go to [https://demo.spid.gov.it/](https://demo.spid.gov.it/), and select **Registra Metadata Service Provider**. 2. Insert your metadata URL in the "Metadata URL" box. 3. Select **Download** to register your domain with SPID. On the screen, you should see the same XML (SAML 2.0) metadata document as the one hosted at your Signicat metadata URL. You have now registered your metadata on the SPID demo environment. Return to the Signicat Dashboard to test SPID. :::info Metadata and domains Your metadata URL is associated to your Signicat domain. If you create a new domain in the Signicat Dashboard and intend to use that when connecting to SPID, then you need to register the new metadata URL with AgID. ::: :::tip Register metadata We recommend registering your metadata URL with AgID every time you test your connection to SPID. ::: ### Run a test 1. In the Signicat Dashboard, navigate to **Products** > **eID and Wallet Hub** > [**eIDs**](https://dashboard.signicat.com/bca/authn). 2. Select **Test eIDs** in the top right. 3. Optional. Choose SPID, if you activated other eIDs. In production, your end-users can choose among the eIDs active in your account. Learn about how to control this in the [IdP scoping](/docs/eid-hub/concepts/idp-scoping.mdx) documentation. 4. Select the **Entra con SPID** ("Login with SPID") button to expand the list of supported identity providers. Then, select **SPID Demo** from the list. 5. In the SPID demo environment, enter the credentials of a [test user](/identity-methods/spid/test.mdx#test-users). For example, use: - *Nome utente* (username): `lucrezia` - *Password*: `password123` 6. Select **Entra con SPID** to proceed. On the next page, select **Conferma** to give consent to the processing of the personal data fields displayed on screen. :::info How would this work in production? In a live scenario in production, the end-user would get redirected to the redirect URL configured through an authentication protocol. Learn how to integrate with a protocol in the [Set up SPID](/identity-methods/spid/setup.mdx) guide. ::: ## Test users To be able to test your SPID implementation, you need a test user. You can get a list of test users from the SPID Demo environment: [https://demo.spid.gov.it/users](https://demo.spid.gov.it/users) Here is an example of available test users: :::CustomTable | Username | Password | First name | Last name | Identity Type | SPID LoA | Deactivated | | ---------- | ----------- | ---------- | ---------- | ------------- | ------------ | ----------- | | lucrezia | password123 | Lucrezia | Borgia | 1 | SPID Level 1 | | | lapulzella | password123 | Giovanna | D'Arco | 1 | SPID Level 2 | | | marcopolo | password123 | Marco | Polo | 1 | SPID Level 3 | | | agid | password123 | | | 2 | SPID Level 2 | | | Louis | password123 | Louis | Armstrong | 3 | SPID Level 3 | | | montessori | password123 | Maria | Montessori | 4 | SPID Level 3 | | | dino | password123 | Dino | De Sauro | | SPID Level 1 | true | ::: --- ## Use cases(Spid) The SPID can be integrated in the digital services of the public administration or on private websites. Below, you can find some of the most common use cases: **Digital onboarding** When becoming a customer of a bank, or registering on any private-sector website, you must first create a user account. In this process, the bank can rely on the identification by the identity provider and the level of assurance to verify your identity and obtain the necessary personal identifiable information. The **SPID registration flow** is specifically designed to support such onboarding scenarios. **Authentication** Once you are a registered customer, you can access your bank's digital services. To log in to your bank, you must authenticate yourself and confirm your identity. With your unique SPID credentials, the bank can reliably recognise you on subsequent visits. The **SPID authentication flow** is therefore well suited to this use case. **Age verification** All Italian citizens aged 18 and over can activate SPID through authorised identity providers. Operational guidelines for issuing SPID credentials to minors are currently being finalised. For technical integration details, see [Setup of SPID](/identity-methods/spid/setup.mdx). --- ## Suomi.fi e-Identification :::note Documentation coming soon If you want to integrate with Suomi.fi e-Identification, contact us for more information and technical documentation: [**Contact an expert**](https://www.signicat.com/contact/contact-sales) :::