Configuration options for your OCEAN's IdP

Owned by Nina Kovač
Last updated: Oct 09, 2024
5 min read

Introduction

In this guide, we will discuss what are Ocean Identity Provider configuration options to manage authentication. Each business partner operates as a separate instance, ensuring secure and isolated management of users and applications.

Identity provider organizes these instances through realms. A realm is a dedicated space where you manage objects such as users, applications, roles, and groups. Users belong to and log into specific realms, and each realm is isolated from the others. This isolation ensures that each business partner can only manage and authenticate its own users.

Realm configuration

The following sections outline the configuration areas within a realm:

  • Users and Groups: Realms have their own user stores and user management systems. Users and groups are specific to each realm and cannot be shared between realms.

  • Applications: Applications are registered at realm level.

  • Roles and Role Mappings: Roles are defined at the realm level and can be assigned to users within that realm. Role mappings are also specific to the realm.

  • Identity Brokers and Identity Providers: Each realm can configure identity brokering settings (e.g., social logins) and have its own set of identity providers.

  • Authentication Flows: Authentication flows, which define how users authenticate, are customizable at the realm level.

  • Security Defenses and Policies: Settings related to brute force detection, password policies, and other security configurations are managed at the realm level.

  • Client Registration and Client Scopes: Realms handle client registration settings and available client scopes.

  • Global Configuration Settings: Certain global settings, such as themes, email configurations, and realm-specific settings (e.g., login themes), are managed at the realm level.

Registered Applications

Within each realm, we can register multiple applications. Registered applications can be:

  • land_operator_app: Ocean’s Operator portal

  • land_fleet_app: Ocean’s Fleet Manager portal

  • land_driver_android_app: Ocean’s Driver Android app

  • land_driver_iOS_app: Ocean’s Driver iOS app

  • land_urchin_app: Ocean’s Urchin integration app

Additional apps may be added in the future. It is not mandatory to use all the apps listed.

Realm Roles

Roles in realm depend on used applications. Default ones are:

  • land_operator: Authorizes user access to the Operator portal

  • land_driver: Authorizes user access to the Driver portal

  • land_fleet_manager: Authorizes user access to the Fleet Manager portal

  • land_urchin_user: Authorizes user access to the Urchin portal

  • land_brokered_identity: User uses external identity provider.

Realm settings

Email

Identity provider can send emails to users for verifying email addresses, resetting passwords, or notifying administrators about server events. To enable email functionality, configure your SMTP server settings:

  • Connection

    • Host

    • Port

    • Encryption

      • Enable SSL

      • Enable StartTLS

    • Authentication

      • Username

      • Password

  • Template

    • From

    • From display name (optional)

    • Reply to (optional)

    • Reply to display name (optional)

    • Envelope from (optional)

Themes

You can customize the appearance of the Identity provider screens for a given realm using themes:

  • Login Theme: Customize login, OTP, grant, registration, and forgot password pages.

  • Account Theme: Customize the user account management console.

  • Admin Theme: Customize the administration console.

  • Email Theme: Customize the emails sent by the server.

image-20241008-103927.png
Login screen theme

Localization

Ocean Identity provider UI supports multiple languages, including:

Arabic, Catalan, German, Greek, English, Spanish, Persian, French, Finnish, Italian, Japanese, Lithuanian, Latvian, Dutch, Norwegian, Polish, Brazilian Portuguese, Russian, Swedish, Ukrainian, Chinese, Chech, Danish, Hungarian, Slovak, Thai, Turkish.

You can override default translations as needed.

Brute force detection

Ocean Identity provider provides settings to handle brute force detection:

  • Actions on detection:

    • Lockout user permanently

    • Lockout user temporarily (default)

    • Lockout permanently after temporary lockout

    • Nothing

  • Settings:

    • Max login failures (default: 30)

    • Wait increment (default: 1min)

    • Max wait (default: 15min)

    • Failure reset time (default: 12h)

    • Quick login check milliseconds (default: 1000) - If a failure happens too quickly, lock out the user.

    • Minimum quick login wait (default: 1min)

External identity providers

External identity providers allow users to authenticate via social networks or identity brokers.

  • Custom Identity Providers:

    • OpenID Connect v1.0: Integrate with identity providers implementing the OpenID Connect protocol.

    • SAML v2.0: Integrate with identity providers implementing SAML.

  • Social Identity Providers:

    • BitBucket, Facebook, GitHub, GitLab, Google, Instagram, LinkedIn, Microsoft, Openshift v3, Openshift v4, PayPal, StackOverflow, Twitter

Example

Realm uses Azure AD for operator logins and Google and Facebook for driver logins. Register Azure AD as an identity provider with OpenID Connect integration, for Google and Facebook, use the existing social providers.

To register an OpenID Connect provider, you need the following information:

  • Alias: If the provider is for a specific application, prefix it with the application name (e.g., land_operator_app_azure).

  • Display Name: Friendly name for the identity provider.

  • Discovery Document URL

  • Client ID

  • Client Secret

  • PKCE Usage

Ocean Identity provider provides a redirect URL that must be added to the external provider as a valid redirect URL.

Authentication

Ocean Identity provider supports various authentication flows:

  • Browser: Browser-based authentication flow.

  • Clients: Services authentication flow.

  • First Broker Login: Actions taken after the first broker login with an identity provider account not yet linked to the identity provider account.

  • Reset Credentials: Reset credentials for a user if they forgot their password.

These flows can be overridden.

Custom Authentication flow examples

First external provider login

For first external provider login (e.g., Azure), automatically link the user with the external provider account without user confirmation and email verification.

Post External provider login

After every external account login, check if user has required roles. E.g., operator role - to be able to access operator portal and brokered role, which allow user to login with external provider.

Required actions

Ocean identity provider supports several actions that can be enabled, set as default actions, or manually triggered:

  • Configure OTP (default: enabled)

  • Terms and conditions (default: disabled)

  • Update Password (default: enabled)

  • Update Profile (default: enabled)

  • Verify Email (default: enabled)

  • Delete Account (default: disabled)

  • Update User Locale (default: enabled)

  • Verify Profile (default: disabled)

Policies

Password Policy

Configure the following password policy settings:

  • Expire Password: Number of days before a new password is required.

  • Hashing Iterations: Number of times a password is hashed before storage or verification (default: 27,500).

  • Not Recently Used: Prevents reuse of a recently used password.

  • Password Blacklist: Prevents use of blacklisted passwords.

  • Regular Expression: Requires the password to match specific Java regular expression patterns.

  • Minimum Length: Minimum number of characters required.

  • Not Username: Password cannot match the username.

  • Not Email: Password cannot match the email.

  • Special Characters: Number of special characters required.

  • Uppercase Chars: Number of uppercase letters required.

  • Lowercase Chars: Number of lowercase letters required.

  • Digits: Number of numerical digits required.

  • Maximum Authentication Age: Maximum age of an authentication session before requiring re-authentication.

  • Maximum Length: Maximum number of characters allowed.

OTP Policy

Configure the following One Time Password (OTP) settings:

  • OTP Type: Time-based (default) or Counter-based.

  • OTP Hash Algorithm

  • Number of Digits: 6 (default) or 8.

  • Look Around Window: Defines how far around the server should look to accommodate time or counter sync issues (default: 1).

  • OTP Token Period: Default is 30 seconds.

Supported applications include FreeOTP, Google Authenticator, and Microsoft Authenticator.

Default lifetimes

  • Access token lifespan: 5min

  • Session: 30min (refresh token renewal)

  • Session max: 10h (login required)

  • Initiated action lifespan: 12h (e.g., reset password link expiration)