Curity logo Documentation
  • Visit curity.io
  • Curity Developer Portal
    Curity Developer Portal
    Downloads Support Resource Library Libraries and SDKs OAuth Tools
  • Contact

  • Home

Table of Contents

  • System Admin Guide
    • Alarms
      • Overview
        • Terminology
        • The Alarm Object
        • Sliding Window Alarms
        • Managing Alarms
        • Notifications
        • Clusters
      • Alarm Types
        • Expiry
        • Failed Authentication
        • Failed Communication
        • Failed Connection
        • Slow Connection
      • Alarm Handlers
        • Email Notifier
        • Webhook Notifier
        • Slack Notifier
        • PagerDuty Notifier
      • Testing Alarms
        • Testing Alarms using the Web UI
        • Testing Alarms using the CLI
        • Verifying the alarm
    • Attribute Transformers
      • Regex Transformer
        • Regex transformation examples
      • Data Source Transformer
        • Data Source Transformation example
      • Script Transformer
    • Audit
      • Configuration
        • Logger
        • File Appender
        • Database Appender
      • Audit Data
        • Mandatory
        • Optional
      • Audit Events
        • profile-added
        • token-introspected
        • refresh-token-issued
        • refresh-token-revoked
        • access-token-issued
        • access-token-revoked
        • id-token-issued
        • initial-dcr-access-token-issued
        • initial-dcr-access-token-consumed
        • initial-dcr-access-token-revoked
        • dcr-client-registered
        • user-info
        • authorization-code-issued
        • authorization-code-consumed
        • delegation-issued
        • delegation-revoked
        • account-created
        • accounts-linked
        • account-activated
        • scim-account-updated
        • scim-account-created
        • scim-account-deleted
        • access-token-authentication
        • client-authentication-success
        • client-authentication-failure
        • cat-verification-failed
        • logout
        • user-authentication-success
        • user-sso-authentication-success
        • sso-session-created
        • bc-authentication-start
        • bc-authentication-success
        • bc-authentication-failure
    • Authorization Managers
      • Groups Authorization Manager
        • Group Rules
      • Scope Authorization Manager
        • Policies, Actions and Rules
        • Configuration
        • Use with OpenID Connect User Info
      • Attribute Authorization Manager
        • Configuration
        • Limitations
        • Examples
    • Credential Managers
    • Cryptography
      • Configuring certificates
      • Configuring private keystores
        • Using an action to add a keystore
        • Preparing the keystore for embedding in an XML configuration document
      • Converting KeyStores (keystore-entry) into correct PKCS12 format
        • Usage of the convertks script
      • Working with PKCS1 private keys
      • Hardware Security Module
        • Entering a PIN
        • Configuring the HSM
        • Debugging the PKCS#11 Provider
      • EdDSA support
    • Data Sources
      • Overview
        • Configuration Strategy
        • Data Source Usage
      • JDBC
        • Table management
        • Database maintenance
        • Quoted identifiers
        • Configuration
        • Clustering
        • Connection Pool Metrics
        • MySQL and MariaDB
        • Microsoft SQL Server
        • PostgreSQL and CockroachDB
        • Oracle
        • HsqlDB
      • LDAP
        • LDAP for Account and Credential Data Access
        • LDAP for Attribute Data Access
        • Use-case for configuring an LDAP backend for HTML Forms authenticator
        • Connection Pool
      • SCIM
        • SCIM 1.1
        • SCIM 2.0
      • JSON / REST Data Source
        • Configuration
      • DynamoDB
        • Table management
        • Database maintenance
        • User Management Service
        • Configuration
      • Multi-zone
        • Configuration
    • Deployment
      • Cluster
        • Two Node Setup
        • Standalone Admin Setup
        • Asymmetric Setup
      • Scalability
      • Creating a Cluster
        • Preparing Configuration
        • Setup Nodes
        • Service Role
        • Viewing Connected Nodes
        • Cluster Lifecycle
      • Deploying with Docker
        • Building a Docker Container
        • Running with docker-compose
      • Multi-region Deployments
        • Authorization flows - Front-channel
        • Authorization flows - Back-channel
        • Data sources
    • Email Providers
      • SMTP Email Provider
        • DomainKeys Identified Mail
      • Configure Email Provider for a Service
    • Http Clients
      • Introduction
      • HTTP Client Configuration
        • Scheme
        • Connection Pool
        • Caching
        • Authentication
        • TLS (encryption)
        • Proxies
      • Metrics
    • Logging
      • Log Levels
      • Configuration Overview
      • Appenders
        • Standard Out
        • Cluster Log
        • Request Log
        • Audit Log
        • Metrics
      • Loggers
      • Masking
      • Shipping Logs
      • Log4j Scripting Languages
      • Files Not Configurable by Log4j
        • Configuration Service Logs
    • Monitoring
      • JMX
      • Tracing
      • Zulu Flight Recorder
        • Starting a Recording Manually
        • Starting a Recording from the Command Line
        • Starting a Recording on Startup
      • Status Endpoint
        • Command line tool
      • Prometheus-compliant Metrics
        • Common Alerts
        • Configuration
    • Scripting
      • Introduction to scripts
        • Procedures during authentication
        • Procedures during token issuance and processing
      • Configuring Scripts
        • Script Types
        • Preparations
        • Configuring using etc/init
        • Writing Scripts
    • Server Events
      • Event Listener Types
        • Script EventListeners
        • EventListener Plugins
      • Types of Events
    • SMS Providers
      • Twilio Sms Provider
      • REST Sms Provider
    • Transport Layer Security
      • Server Name Indication
    • Upgrading
      • Upgrading from 6.0.X to 6.1.0
        • Apache Velocity Engine
      • Upgrading from 6.1.X to 6.2.0
        • Upgrading the XML Configuration
        • Logging of BankID messages
      • Upgrading from 6.2.X to 6.3.0
        • Upgrading the XML Configuration
        • Updating Templates
        • RESTCONF Conformance Updates
        • TLS 1.0 and 1.1 Disabled
        • SDK
      • Upgrading from 6.3.X to 6.4.0
        • Default Java Options Changed
        • Java Upgraded to Version 11
        • SDK
        • Changes to the HAAPI Web SDK
        • DPoP Proof Token Clock Skew
        • DN Certificate Validation
      • Upgrading from 6.4.X to 6.5.0
        • BankID Authenticator and Signing Consentor Messages
        • Logging Changes
      • Upgrading from 6.5.X to 6.6.0
        • Relaxation of DN Certificate Validation
        • Changed Default for Maximum Number of Request Threads
      • Upgrading from 6.6.X to 6.7.0
        • Updating Databases
        • Removal of OpenSSL dependency
        • Redirect URI validation
        • Template Updates
      • Upgrading from 6.7.X to 6.8.0
        • SDK Changes
        • Serialization
        • TLS
        • RESTCONF
        • Template Updates
        • Deprecation of the Net iD Authenticator
        • BankID authenticator
        • BankID Consentor
      • Upgrading from 6.8.X to 7.0.0
        • Upgrading the XML Configuration
        • SDK Changes
        • Java Upgraded to Version 17
        • Procedures API Changes
        • Log4j2 Changes
        • Database Changes
        • Prometheus Metrics
        • Validation for Endpoint URIs Changed
        • NetiD Access Authenticator
        • BankID Authenticator and Signing Consentor
      • Upgrading from 7.0.X to 7.1.0
        • HAAPI DPoP improved processing
        • Template and message updates
      • Upgrading from 7.1.X to 7.2.0
        • SDK Changes
        • Logging Changes
      • Upgrading from 7.2.X to 7.3.0
        • Authentication Action Attributes
      • Upgrading from 7.3.X to 7.4.0
        • Email templates in Authentication Actions
        • Startup script changes
        • User Management with GraphQL
        • DynamoDB schema changes
      • Upgrading from 7.4.X to 7.5.0
        • HTTP Client Default Timeouts
      • Upgrading from 7.5.X to 7.6.0
        • Systemd config file update
        • New SAML Authenticator
      • Upgrading from 7.6.X to 8.0.0
        • Upgrading the XML Configuration
        • Authorization custom token procedures update
        • DynamoDB schema changes
        • WebAuthn authenticator
        • HAAPI capability and use of legacy DPOP
        • Microsoft SQL Server JDBC driver
        • Changes to HAAPI responses
        • Password-based PBES2 JWE algorithms
        • Windows Connector Failover Update
      • Upgrading from 8.0.X to 8.1.0
        • Database Changes
        • Custom Token Issuers
        • Email Authenticator
      • General Upgrade Procedure
        • Preparing the upgrade
        • Performing the upgrade
        • After the Upgrade
    • DevOps Dashboard
      • Enabling the DevOps Dashboard
      • Requirements of an OAuth Client
      • Group Access
      • Availability
    • System Requirements
      • Operating Systems
      • Minimum Hardware Requirements
      • Recommended Hardware Setup
      • Hypermedia Authentication API
      • Browsers
      • Database
      • User Repositories
      • Networking
      • Hardware Security Module
      • File Encoding
      • HTTP
      • TLS
    • JVM Configuration
      • Changing JVM Settings in the Admin UI
      • Changing the JVM Settings with the CLI
    • Go-live Checklist
      • General System
      • Related Systems
      • All Profile Types
      • Authentication
      • Token Service
      • User Management
      • Configuration
      • Clustering
    • CORS
    • Cross Site Requests
  • Authentication Service Admin Guide
    • Overview
      • Authenticators
      • Actions
      • Single Sign-On (SSO)
      • Logout
      • Account Domains
      • Validation Procedures
      • Authenticator Filters
      • Service Providers
      • Protocol Plugins
      • Automatic login
    • Defining an Authentication Service Profile
      • Preparing the Authentication Service Profile
        • Pre-requisite configuration
      • Base Configuration of an Authentication Service Profile
        • Example Create request
    • Authenticators
      • Overview of Authenticators
        • Authenticator purpose
        • Authenticator Base Configuration
        • Multi-factor configuration for Authentication
        • Back-channel Authenticators
      • BankID
        • Integrating with BankID
        • Kinds of BankIDs
        • Trusted BankID Provider
        • Authentication flows
        • Configuration settings
        • Testing the Integration and Configuration
        • Persisting the BankID Responses
      • Duo
        • Configuration Settings
        • Creating a New Authenticator
        • Logging In
      • Dynamic Authenticator
        • Configuration
        • Delegate Authenticator
        • Dynamic Configuration Source
        • Configuration Example
        • Example Use-case
      • Email
        • Base Configuration
        • Using as standalone factor (single factor)
        • Using as second or N-th factor
        • Using an Intermediate Attribute
        • Hyperlink
        • Inactive Accounts
        • Configuration
      • Encap
        • Basic Configuration
        • Registration During Login
        • Additional Information Before Registration
        • Automatic Login
      • Entrust IDaaS
        • Creating an App in Entrust
        • Creating a new Authenticator
      • Facebook Authenticator
        • Configuring Facebook
        • The Redirect URI
        • Configuration in the Authentication Service
      • Google Authenticator
        • Configuring Google
        • The Redirect URI
        • Configuration in the Authentication Service
      • HTML Forms Authenticator
        • Paths
        • Validation Scripts
        • Email Provider
        • Automatic Login
        • Password Only
        • Remember Me
        • Configuration
      • OpenID Connect Authenticator
        • The Redirect URI
        • JWKS Endpoint
        • Configuration
      • PingFederate IdP Adapter Authenticator
        • Authentication Flow
        • Configuration
      • PingFederate
      • SAML
        • Paths
        • Validation Scripts
        • Configuration
        • Known limitations
      • SAML2
        • Paths
        • Validation Scripts
        • Configuration
        • SAML2 dynamic authenticator
        • Known limitations
      • Sign in with Apple
        • Configuring a Sign in with Apple Service
        • Setting up the authenticator
      • SITHS
        • Configuring an Authenticator
      • SMS OTP
        • Base Configuration
        • Using as standalone factor (Single factor)
        • Using as second or N-th factor
        • Using an Intermediate Attribute
        • SMS OTP in OTP mode
        • SMS OTP in Hyperlink mode
        • Registration
        • Automatic Login
        • Configuration
      • TOTP - Time base One Time Password
        • Configuring an Authenticator
        • Configuring for pre-shared keys
        • Configuring for generated keys
        • Automatic Login
      • Twitter
        • Creating an App in Twitter
        • Configuring the Twitter Authenticator
      • Username
        • Configuration
        • Source Code
      • WebAuthn / Passkeys
        • Device Types
        • Configuring a WebAuthn authenticator
        • Registering devices
        • User Interaction for platform devices
        • Hypermedia Authentication API
        • iOS Domain Association
        • Android Domain Association
        • Known limitations
      • Windows
        • Installing the Windows Connector
        • Configuring an Authenticator
        • Configuring the Windows Connector
        • Troubleshooting
    • Authentication Actions
      • Overview
        • Login Actions
        • SSO Actions
        • Actions and Action Completions
        • Action attributes
      • Attribute Prompt Action
        • Configuration
        • Localization
      • Auto Create Account
        • Creating accounts
        • Configuration
        • Default Values in the account
        • Errors
      • Auto Link Accounts
        • Overview
        • Configuration
        • Advanced
        • User Confirmation
      • Conditional Multi-Factor
        • Attribute Enable Condition
        • Attribute ACR Condition
        • Subject Condition
        • Client Property Condition
        • Subject Check
      • Copy Attribute
        • Configuration
      • Data Source Transformer Action
        • Transforming values using data source values
        • Include additional values from datasource
        • Configuration
      • Date/Time Deny Action
      • Debug Attribute Action
      • Deny Action
        • Configuration
      • Geolocation Allow or Deny Country Action
        • Configuration
      • Geolocation Changed Country Action
        • Configuration
      • Geolocation Impossible Journey Action
        • Configuration
      • Geolocation New Country Action
        • Configuration
      • Lookup Account
      • Lookup Links Action
        • Overview
        • Configuration
      • Opt-In MFA
        • Registering a New Factor
        • Managing Factors
        • Recovery Codes
        • Configuration
      • Regular Expression Transformer Action
        • Transforming values using regular expressions
        • Excluding attributes
        • Renaming attributes
        • Configuration
      • Remove Attribute Transformer Action
        • Configuring attributes for removal
      • Request Acknowledgement
        • Localization
        • Configuration
      • Reset Password
        • Configuration
        • Example Usage
        • Errors
      • Resolve Account Link
        • Overview
        • Configuration
      • Restart Action
        • Configuration
      • Script Transformer Action
        • Transforming values using script procedures
        • Configuration
      • Selector
        • Configuration
      • Send Email Action
        • Configuration
        • Templates
      • Sequence Action
        • Configuration
      • Set Attribute
        • Configuration
      • Switch Action
        • Conditions
        • Configuration
      • Time-based Deny Action
      • Update Account
        • Configuration
      • Zone Transfer
        • Configuration
        • Errors
    • Multi-Factor Authentication
      • Using a chain of authenticators
        • More than two factors
        • Single Sign-On and Multi-Factor
        • Freshness and Forced Authentication
        • Using the ACR Parameter
      • Using a Multi-Factor Authentication Action
    • Account Linking
      • Basic Concepts
        • Example of Linking with Facebook
        • Example of Linking with Facebook as Second authenticator
      • Resolving Links
      • Looking up Links
      • Common Linking Flows
        • Linking a foreign account and adding links to the result
        • Linking using the foreign authenticator and resolving immediately
        • Linking using the local authenticator, resolving on next login with foreign
        • Linking two foreign accounts using auto create account
        • Linking two foreign accounts using auto create & resolving on next login
    • Protocol Plugins
      • PingFederate
        • Configuring PingFederate
        • Adapter Configuration
        • Configuring the Authentication Service
      • SAML
        • SAML protocol
        • Configuring the Authentication Service
        • Service Provider (App) integration
        • Federation Server integration
        • SAML Logout
    • Account Manager
      • Registration - Create account
      • Username is Email
    • Service Providers
      • Introduction
      • Managing Service Providers in the Admin UI
      • Framable User Interface
        • Multiple values for ‘allowed-origins’
        • Origin URI pattern format
      • Original Query retry integration
        • Example
        • Example OAuth Client
      • Third Party Cookies
        • Steps to Integrate Preflighting
        • Advanced Preflight behaviour
        • Disabling the Preflight Resource
    • Authenticator Filters
      • User-Agent Authenticator Filter
      • CIDR Authenticator Filter
      • Script Authenticator Filter
      • Geolocation Authenticator Filter
    • Single Sign-On
      • Requirements for SSO
      • Session Duration
        • Session cookies vs Persisted Cookies
        • Database persisted session
        • Expiration
        • Example
      • Overriding SSO
        • Freshness
        • Forcing authentication
    • Automatic Login
      • Authenticator Availability
    • Logout
      • Endpoint
      • Redirect After Logout
        • Using configuration
        • Using query parameter
      • Configuration
    • Geolocation
      • Geolocation Database File
      • Geolocation Actions
        • Geolocation Allow or Deny Country Action
        • Geolocation Changed Country Action
        • Geolocation Impossible Journey Action
        • Geolocation New Country Action
      • Geolocation authenticator filter
      • Geolocation authenticator settings
  • Token Service Admin Guide
    • Introduction to the Token Service
    • Defining an OAuth Profile
      • Preparing the OAuth Profile
        • OpenID Connect
        • Pre-requisite configuration
      • Base Configuration of an OAuth Profile
        • Example create request
    • OAuth Flows
      • Code
        • Proof Key for Code Exchange
      • Implicit
      • Client Credentials
      • Resource Owner Password Credentials
      • OpenID Connect Hybrid Flows
      • OpenID Connect CIBA Flow
        • Signed Authentication Request
      • Token Exchange
      • Assisted Token
      • Refresh
      • Revoke
      • Introspect
      • Json Web Key Set (JWKS)
      • Device Flow
      • Assertion Flow
        • Token reuse
      • Logout Flow
    • Using the device flow
      • Configuration
      • Endpoints
        • Device Authorization
        • UserCode Verification
        • Token Endpoint
      • Token Procedures
      • Templates
    • Scopes and Claims
      • Adding a scope to the profile
      • Adding a scope to a client
      • Scope Lifetime
      • Required scopes
      • Prefix scopes
        • Customizing prefix scope templates and messages
      • Claims of a scope
      • Claims I/O
        • Claim mappers
        • Claim value providers
        • Configuring a claim
    • Configuring OAuth User Authentication
    • OpenID Connect
      • Metadata
      • The “claims” request parameter
      • Issuing pseudonymous subject identifiers
        • Client settings
        • Profile settings
        • Sector Identifier for Dynamic Client Registration
    • Dynamic Client Registration
      • Architectural Overview of Dynamic Client Registration
        • Deployments and Configurations
        • Initial Access Token
        • Registration
        • Registration Based on a Template Client
        • Registration Based on a Non-templatized Client
      • Enabling Dynamic Client Registration
      • Dynamic Client Registration Management (DCRM)
        • Client Certificates and DCRM
        • DCRM Management Clients
      • Dynamic Client Management With GraphQL
      • Dynamic Client Registration API
        • Templatized Dynamic Client Registration
        • Non-Templatized Dynamic Client Registration
      • Custom Client Properties
    • OAuth Client Configuration
      • Client Capabilities
        • Hybrid Capabilities
      • User Authentication
      • Client Authentication
        • Client Secret
        • Client Assertion
        • Secondary authentication
      • Client Framability
        • Examples
      • Redirect URI validation
        • Validation policies
        • Using Validate Port on Loopback Interfaces and Allow Per Request Redirect URIs (deprecated)
    • Issuing OAuth and OpenId Connect Tokens
      • Default Token Issuers
      • Custom Token Issuers
      • More on Wrapped Opaque Tokens
      • Encrypted ID Tokens
    • OAuth Endpoint Reference
      • Anonymous
      • Authorize
      • Assisted Token
      • Introspect
      • Revoke
      • Token
    • User Consent
      • Consenting to requested claims
        • Example
      • Asking for consent
        • Example user consent gathering
        • Example with prompt
      • Enabling user consent
      • The user consent template
        • Example claim localization
        • Showing prefix scopes
      • Consentors
    • Consentors
      • BankID
        • Integrating with BankID
        • Signing Consent Data
        • QR Code
        • Asking user for personal number
        • Signing cancellation
        • Configuration settings
        • BankID Consentor Response
        • Testing the Integration and Configuration
        • Persisting the BankID Responses
      • Profile configuration
      • Client configuration
      • Consentor selection
      • Consentor templates
      • Consentor result
    • Mutual TLS Authentication
      • TLS termination
      • Binding certificates to tokens
      • Trusted certificates
        • Trust by PKI
        • Trust by a pinned certificate
      • DN comparison
      • Subject Alternative Name
      • Configuring Mutual TLS
        • Proxy terminated Mutual TLS
        • Direct terminated Mutual TLS
        • Configuring trust
      • Reverse Proxy Server Setup
        • Generic Reverse Proxy Server Setup
        • Setting Up NGINX As a Reverse Proxy Server
        • Setting Up HAProxy As a Reverse Proxy Server
        • Setting Up Apache HTTPD 2.x As a Reverse Proxy
      • Non-Templatized Dynamic Client Registration using Mutual TLS
        • OrganizationIdentifier
        • Match only organizationIdentifier
    • OpenID Connect Issuer Discovery
    • Financial-grade Security
      • JWT Secured Authorization Request (JAR)
      • Pushed Authorization Requests
      • Request Object Handling
      • JWT Security Authorization Response Mode (JARM)
      • Encrypted ID Tokens
    • Session Management and Logout
      • Session Endpoint
      • Logout
        • Logout Notification
      • OpenId Connect specifications for Session Management and Logout
    • Token Procedure Plugins
      • Configuring and using Token Procedure Plugins
      • Developing Token Procedure Plugins
      • Known limitations
  • User Management Admin Guide
    • Overview
      • SCIM 2.0
        • Users
        • Devices
        • Delegations
        • External ID
        • Custom claims
      • GraphQL
        • Queries and Mutations
        • Introspection
        • Authorization
        • Custom Attributes
        • Data Sources
        • More Details
      • OAuth Protected
    • Defining a User Management Service Profile
      • Preparing the User Management Service
        • Pre-requisite configuration
      • Step by step guide to setup a User Management Service
        • 1. Add the profile
        • 2. Select OAuth Service
        • 3. Select User Account Data Source
        • 4. Select OAuth Delegations Data Source
        • 5. Setting up the endpoints
        • 6. Exposing the Endpoints on a Service (node)
        • 7. Commit the changes
  • Developer Guide
    • Authentication Service
      • Authenticators
        • Authenticators
      • Endpoints
        • Authentication Endpoint
        • Registration Endpoint
        • Anonymous endpoint
        • Authenticators
    • OAuth Service
      • Web Clients
        • Assisted Token JavaScript API
      • CORS on the OAuth Server
        • Default CORS Enabled Endpoints
        • Endpoints that Can be CORS Enabled
    • Data Sources
      • Using SCIM v1.1 as Data Source
        • Client Authentication
        • Required SCIM operations
      • JSON Data Source
        • Credential verification
        • Attribute Provider
        • Bucket Access
        • Authentication
    • SMS REST Client
      • Sending a message
      • Response and Errors
      • Authentication
    • Email Provider Plugin
      • SMTP Plugin’s message contents rendering
    • Front-End Development
      • Introduction
      • Understanding the Templating System
        • The Template Override System
        • Overrides
        • Template Areas
        • Serving templates via the anonymous endpoint
        • Error templates
        • Common Template Variables
        • Never Remove CSP
      • Using the UI Builder
        • Setting up the environment
        • Running the previewer
        • Working with velocity variables
        • Overriding templates
        • Working with template areas
        • Working with translations
        • Building
      • Customizing the Look and Feel
        • Creating Custom Themes in the Admin UI
        • How to create your custom theme in UI Builder
        • How to work with Sass
        • Themes
        • Using External Web Fonts
        • Compiling Sass to CSS
        • How to work with the settings file
      • Localizing Resources
        • About Locales
        • Using localized messages in templates
        • Message keys
        • Message lookup
        • Message Files Format
        • Using plugin-specific messages in re-usable templates
      • Secure Iframing
        • Pre-requisites
      • API Driven UI
    • Scripting Guide
      • Credential Transformation Procedures
        • Function
        • Examples
      • EventListener procedures
        • Configuring EventListener Procedures
        • Common API
        • EventListener functions
      • Filter procedures
        • Function
        • Common API
        • API
      • Global Scripts
        • Common API
        • Global Constants
      • Token procedures
        • Issuing tokens
        • Token Procedure Function Signature
        • Including Request Parameters Values
      • Token Procedure API
        • Context
      • Token Procedure Examples
        • Overview
        • Assisted Token Endpoint
        • Authorize Endpoint
        • Introspection Endpoint
        • Token Endpoint
        • UserInfo Endpoint
      • Transformation Procedures
        • Common API
        • Function
        • Return Value
        • Examples
      • Userinfo procedures
        • Common API
        • Claims
        • Common API
        • Function
        • Return Value
        • Examples
      • Validation procedures
        • Common API
        • Function
        • Return Value
        • Examples
      • Pre-Processing Procedures
        • Function
        • Return Value
        • Examples
      • Post-Processing Procedures
        • Function
        • Return Value
        • Examples
      • Common Procedure API
        • Common Procedure Objects
        • Procedure Context object
        • Common Operations Examples
      • Developing Procedures
        • Logging
        • Exceptions
    • Plugins
      • Access to the Curity Release Repository
      • Plugin Installation
        • Classpath considerations
      • Basic structure of a plugin
        • SmsSender Plugin Example
      • Managed Objects
      • Plugin Services
        • Service Restrictions by Plugin Type
        • Service Restrictions in ManagedObject
      • Cross-site Plugin Handlers
      • Java Version
      • Server-Provided Dependencies
        • SLF4J Logging API
        • Bean Validation API
        • Hibernate Validator Engine
        • Kotlin Standard Library
      • Serialization
    • Hypermedia Authentication API
      • Introduction
      • Access control
        • Client attestation
        • Android client attestation configuration
        • iOS client attestation configuration
        • Browser (Web) client attestation configuration
        • Disabling attestation for testing purposes
        • Debugging Web CAT problems
      • Flow state management
      • API Driven UI
      • Examples
        • Example - Username and password based authentication
        • Example - Encap authentication with device registration
        • Example - Using an external browser
      • SDK
        • HAAPI Android SDK
        • HAAPI iOS SDK
        • HAAPI Web SDK
    • Curity SDKs
      • Java Plugin SDK
      • HAAPI Android SDK
      • HAAPI iOS SDK
      • HAAPI Web SDK
    • GraphQL APIs
      • Using Access Tokens
      • Introspecting the Schema
      • Using Queries
      • Mutation Errors
      • DynamoDB limitations
        • User Management service limitations
        • Dynamic Client Registration service limitations
        • GraphQL error for unsupported features
  • Configuration Guide
    • Overview
      • Transactional configuration
      • Rollbacks and history
      • Factory default
      • Mandatory, optional and default parameters
      • Configuration interfaces
        • Service Roles
        • Profiles
        • Endpoints
        • Using Endpoints in Service Roles
      • Commit Hooks
    • RESTCONF API
      • General Concepts
      • RESTCONF Endpoint
        • URIs
      • RESTCONF Operations
      • Querying Data
      • Rollback using RESTCONF
      • Message Encoding
      • Authentication
    • Command Line Interface
      • Connect to the CLI
      • Modes in the CLI
        • View mode
        • Configuration mode
      • Basic Usage
        • Viewing the configuration
        • Changing the configuration
        • Applying the configuration
        • Rollback changes
      • Advanced Usage
        • Moving through the configuration using Edit
        • Showing selected values only
        • Exporting configuration
        • Loading configuration
        • Multiline Edit Mode
      • Scripting and automation
    • Commit Hooks
      • Commit Hook CLI Scripts
      • Commit Hook Scripts
    • Encrypted Configuration
      • Setup Encryption
        • Defining a key during installation
      • Defining Encryption Key on Startup
      • Change Encryption Key
    • Backing Up the Configuration
      • Using the idsvr Command
      • Using the idsh Command
      • Using the Web UI
      • Using the RESTCONF API
    • Restoring a Saved Configuration
      • Using the idsvr Command
    • Restoring the Initial Configuration
      • Preserving the Configuration Database
      • Deleting the Configuration Database
        • 1. Stop the admin node
        • 2. Remove the running datastore
        • 3. Check the min-conf.xml and key-conf.xml
        • 4. Making sure the default procedures are in place
        • 5. Make sure the appropriate certificates are initialized
        • 6. Start the admin node
    • Parameterized XML Configuration
      • Example:
      • Default Values
      • Using startup.properties
    • Access Control
      • Defining Rules in the Admin UI
        • Rules for the DevOps Dashboard
      • Enforcement of Access Control Rules
    • Configuration Reference
      • Alarms
        • Control
        • Alarm-inventory
        • Summary
        • Alarm-list
        • Shelved-alarms
        • Alarm-profile
      • Environment
        • Localization
        • White-listed-proxies
        • Cluster
        • Admin-service
        • Themes
        • Zones
        • Service-role
        • Runtime-service
        • Reporting
        • Alarms
      • Profile
        • Authentication-service
        • User-management-service
        • Authorization-server
        • Endpoints
        • Token-issuers
      • Facilities
        • Cache
        • Client
        • Data-source
        • Email-provider
        • Sms-provider
        • Crypto
        • Caching-services
        • Client-attestation
      • Processing
        • Token-procedure-plugin
        • Token-procedure
        • Global-script
        • Validation-procedure
        • Transformation-procedure
        • Filter-procedure
        • Event-listener-procedure
        • Claims-provider-procedure
        • Credential-transformation-procedure
        • Pre-processing-procedure
        • Post-processing-procedure
        • Authorization-manager
        • Event-listener
        • Account-manager
        • Credential-manager
      • Base Types
      • Type Reference
        • Types
        • Identities
  • Glossary
  • Docs /
  • Authentication Service Admin Guide /
  • Authentication Actions /
  • Auto Link Accounts

Auto Link Accounts¶

Auto Link Accounts is an action that creates a link between the incoming subject from the authenticator, and another subject found in the authenticated sessions (i.e., SSO sessions).

Note

For a more detailed guide on how to work with account linking see Account Linking.

Overview¶

Auto link account silently creates a link between two subjects – the foreign account and the local account. The local account is the account found in the configured Account Manager. The foreign account is a subject (username) that should be bound to the local account.

It only creates the link if it can find the session of the configured Account Domain in the authenticated sessions. If not, it silently passes without linking.

Configuration¶

Two things are needed for auto-linking accounts:

  1. An account domain configured on the foreign authenticator that should be linked when seen
  2. The auto link accounts action on the other authenticator that should perform the link

The following configuration is needed for linking to work.

Configuration Mandatory Description
linking-account-manager yes Where the account should be linked, also where the local account is present
linking-account-domain yes What account-domain to look for when linking
use-linked-account-as-main-account no (Default false) If true, then the account manager contains the foreign account, so linking is reversed
overwrite-existing-link no (Default false) if a link exist, overwrite it.
advanced/account-id-in-attribute no Use an arbitrary attribute as the account id. This can have very negative implications on your setup, so use with caution.
advanced/account-id-in-attribute-source no Source location for the arbitrary attribute to use as the account id.

If use-linked-account-as-main-account is set to true, then the linking-account-domain is treated as the local account and is expected to be found in the accounts that the linking-account-manager holds, and the current authenticator that the action is configured on is the foreign account. This is also referred to as reverse linking.

Important

When using use-linked-account-as-main-account=true, the current authenticator’s account-domain will be used in the database as the linking domain.

../../_images/auto-link-account-config.png

Fig. 92 Auto Link Account Configuration Dialog

Advanced¶

Account Id in Attribute¶

In some setups, where it is impossible to use the auto-create-account action to link two foreign accounts, an arbitrary attribute can be selected to act as a the account id stored in the link. If use-linked-account-as-main-account is enabled, then this attribute is picked from the Authenticated Sessions, otherwise it is taken from the incoming attributes from the authenticator this action runs on.

The account-id-in-attribute-source setting defines the specific source location, which can be subject-attributes or context-attributes, when using Authenticated Sessions; or subject-attributes, context-attributes, or action-attributes, when using the incoming attributes from the authenticator this action runs on.

Warning

A run time error will be returned on every request using this action if account-id-in-attribute-source is configured to be action-attributes and the configuration is using the Authenticated Sessions as the source for the account id information.

No check is made to verify that the account corresponding to the given ID exists. Doing this might cause several problems as there is no guarantee that the value of this attribute is globally unique and immutable. It is strongly suggested to use a auto-create-account action before this one, instead, to avoid any future issues (see Linking two foreign accounts using auto create account).

Warning

It is strongly recommended to NOT use an attribute that might change such as subject (username) or email.

User Confirmation¶

By default this action will create the link without any user interaction. However, it is possible to ask the user for confirmation before creating the link. This is done via a confirmation screen where the user can allow or deny the link creation.

To enable the user confirmation screen, the user-confirmation setting needs to be added to the configuration. This setting has inner settings that allow the control of the information displayed to the user, namely:

  • Use the value of an alternative attribute for the displayed local account identifier. To be used when the `subject attribute value is not meaningful for the user.
  • Use the value of an alternative attribute for the displayed foreign account identifier. To be used when the `subject attribute value is not meaningful for the user.
  • Change the name of the configured account domain to something that is more meaningful to the user.
Configuration Mandatory Description
user-confirmation no Add if account linking should be subject to user confirmation. By default the account linking is done automatically without any user confirmation.
user-confirmation/attribute-for-local-identifier no Add if the displayed local account identifier should be obtained from an attribute other than subject.
user-confirmation/attribute-for-local-identifier/location no The location from where to retrieve the attribute used for the displayed local account identifier (subject-attributes, context-attributes, or action-attributes). Default value is subject-attributes.
user-confirmation/attribute-for-local-identifier/name yes The name of the attribute used for the displayed local account identifier.
user-confirmation/attribute-for-foreign-identifier no Add if the displayed foreign account identifier should be obtained from an attribute other than subject.
user-confirmation/attribute-for-foreign-identifier/location no The location from where to retrieve the attribute used for the displayed foreign account identifier (subject-attributes, context-attributes, or action-attributes). Default value is subject-attributes.
user-confirmation/attribute-for-foreign-identifier/name yes The name of the attribute used for the displayed foreign acciunt identifier.
user-confirmation/linking-account-domain-name no The name for the displayed foreign domain name used.

Important

The settings under user-confirmation only change the information that is presented to the user and not the information that is stored in the link.

Warning

The action-attributes attribute location will be empty when the information is coming from the authenticated session. This means that this location should only be used for the local account identifier if use-linked-account-as-main-account is false or for the foreign account identifier if use-linked-account-as-main-account is true.

Table of Contents
Copyright © 2015-2023 Curity AB. All rights reserved.