Company delegations (beta)

💡

This feature is currently in closed beta. Contact us at hello@kenni.is for more information on joining the beta program.

Company Delegations allow clients to authenticate company users using registered relations in the Icelandic Company Registry (Fyrirtækjaskrá). This feature enables secure and efficient access management for business-related applications.

Supported Roles

The following roles are supported in the Company Delegations system:

Board Member (Stjórnarmaður)

CEO (Framkvæmdastjóri)

Procuration Holder (Prókúruhafi)

Auditor (Endurskoðandi / Skoðunarmaður)

There are 5 other roles which exist in the company registry but may be less relevant for authorization:

Owner (Eigandi): From the founding documents, may not be maintained as ownership changes.

Founder (Stofnandi): From the founding documents, may not be involved anymore.

Agent (Umboðsaðili): Rarely used.

Branch manager (Útibússtjóri): Rarely used.

Vice Board (Varastjórn): Rarely used.

Configuring Your Application

To enable Company Delegations in your application, you need to configure it properly. Follow these steps:

Go to your application settings in the Kenni developer portal.

Navigate to the "Delegations" tab.

Select different company roles which should be able to authenticate into your application. This may include:

Board Member (Stjórnarmaður)

Chief Executive Officer (Framkvæmdastjóri)

Procurator (Prókúruhafi)

Auditor (Endurskoðandi / Skoðunarmaður)

Save your settings.

By configuring these settings, you ensure that your application can authenticate users with the specified company roles during the delegation process.

Authentication Process

To initiate a delegated authentication, include the following parameter in your authorization request:


prompt=delegation

This will trigger the delegation flow, where the user will be presented with a list of companies they are associated with. The user can then choose the company they wish to authenticate for.

When implementing Company Delegations, consider these UX recommendations:

Separate Login Buttons: Provide distinct login buttons for individuals and companies. This clear separation helps users understand their options upfront and get faster to their end goal. It may also lower your authentication costs.

Post-Authentication Delegation: Alternatively, offer a "switch delegation" action after authentication. Note that this approach requires re-authentication with an electronic ID or passkey

💡

We are currently developing optional Single Sign-On (SSO) functionality to enhance the user experience. This feature will allow users to switch between delegations without requiring multiple authentications with the associated costs.

New Identity Scopes

To retrieve information about the delegation and actor (actual end user), you can request the following new identity scopes:

actor_profile: Basic information about the actor, including their name

actor_national_id: The actor's national ID (kennitala)

actor_phone_number: The actor’s phone number.

delegation_type: The type of delegation in effect.

Include these scopes in your authorization request to receive the corresponding information in the ID token.

Changes in ID and Access Tokens

When using delegated authentication, the subject and primary claims of ID and access tokens refer to the selected company. The tokens may include these additional claims if requested with the new identity scopes above:

actor: Information about the authenticated user,

delegation_type: The type of delegation in effect (e.g., "c:procurator", "c:board", "c:ceo")

Example of claims in an ID token:

json
{
  "sub": "12345", // anonymised company id
  "name": "Acme ehf.",
  "actor": {
    "sub": "67890", // anonymised user id
    "name": "Jón Jónsson"
  },
  "delegation_type": ["c:ceo", "c:procurator"]
}

Assuming an authorization request for these scopes: openid profile actor_profile delegation_type

Implementation Example

Here's a basic example of how to initiate a delegated authentication request:

javascript
const authorizationUrl = `https://idp.kenni.is/domain.is/oidc/auth?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid profile actor_profile&
  prompt=delegation`;

// Redirect the user to the authorizationUrl

After successful authentication, you'll receive an authorization code. Exchange this code for ID and access tokens using your standard token endpoint.

Security Considerations

When implementing Company Delegations, consider the following security aspects:

Always verify the delegation_type claim to ensure the user has the appropriate role for the requested action.

Implement proper scoping of resources based on the authenticated company and delegation type.

Include information from the actor claim as needed in your audit logs.

Regularly audit and review delegations to maintain the principle of least privilege.

Kenni only verifies the delegation during authentication, not when refreshing access tokens. Be sure to limit the lifetime of refresh tokens if that’s a concern.

For more detailed information or to join the beta program, please contact us at hello@kenni.is.