Skip to content
Architecture > Authentication

SAML

3forge supports SAML integration for enterprise-level authentication. Please reach out to us at support@3forge.com if you require and do not have the adapter.

Overview

The SAML adapter enables secure user logins to 3forge applications using the SAML protocol. To use, you will need to ensure that you have the adapter and an identity provider for the SAML response.

Setup

Note

If you have been assigned the SAML adapter separately to your AMI installation, please do the following first:

  1. Download the SAML plugin from your client portal.
  2. Extract the .jar files and paste them into the amione/lib directory of your AMI installation.

You will need to register your 3forge application with the identity provider. The response URL should be the URL of your 3forge application with an additional suffix to identify a SAML login attempt, e.g: your_host_address:3forge_port/suffix.

Warning

URL suffixes cannot be the same as a predefined 3forge URL endpoint, e.g: your_host_address:3forge_port/3forge.

Instead, use something like your_host_address:3forge_port/3forge_saml.

Minimal Configuration

These are the minimum required properties for SAML configured in local.properties: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Include the SAML Plugin
saml.plugin.class=com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl 

# IdP and response URL (service provider)
saml.identity.provider.url=link_to_idp
saml.service.provider.url=link_to_3forge_instance/suffix

# SAML entity ID for application
saml.entityid=3forge_application

# What the username field is mapped to in the SAML response
saml.username.field=NameID

# Set the debugger to true for logging purposes
saml.debug=true

For detailed information on each property as well as additional optional prperties, see the properties section below.

Properties

General

1
saml.plugin.class

Default: com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl

  • Fully qualified class name of the plugin implementing the com.f1.ami.web.AmiWebSamlPlugin interface
  • Use com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl unless implementing a custom version
1
saml.identity.provider.url

Default: User-provided

  • The URL of the identity provider
1
saml.service.provider.url

Default: User-provided

  • The URL of the service provider (equivalent to the reply URL)
  • Must provide a suffix, e.g: saml.service.provider.url=address_to_service_provider/suffix
1
saml.entityid

Default: User-provided

  • The issuer ID as provided by the SAML request
1
saml.relay.state

Default: None (Optional)

  • Adds the RelayState parameter to the request for optional user input
1
saml.username.field

Default: uid (Optional)

  • Name of the attribute field of the response to extract username from
  • For example: Name="username"
1
saml.ami.isadmin.field

Default: true (Optional)

  • Name of the attribute field of the response to extract if a user has admin permissions or not
  • If not supplied, defaults to true
1
saml.ami.isadmin.values

Default: true (Optional)

  • Value of attribute field of the response to extract if a user has admin permissions or not
  • If not supplied, defaults to true
1
saml.ami.isdev.field

Default: true (Optional)

  • Name of the attribute field of the response to extract if a user has dev permissions or not
  • If not supplied, defaults to true 
1
saml.ami.isdev.values

Default: true (Optional)

  • Value of attribute field of the response to extract if a user has dev permissions or not
  • If not supplied, defaults to true
1
saml.ami.group.field

Default: User-provided (Optional)

  • Name of the attribute field of the response to extract group names from
  • For example: user_group
1
saml.ami.groups

Default: User-provided (Optional)

  • Values of the different group names associated to the 3forge groups field
  • For example: group_1,group_2
1
saml.debug

Default: true (Optional)

  • Set to true to show verbose logging on SAML related information

Security

1
saml.identity.provider.cert.file

Default: User-provided (Optional)

  • The file containing the security certificate for the SAML authenticator 
1
saml.identity.provider.clock.skew.ms

Default: 100 (Optional)

  • The amount of time (in milliseconds) that the identity provider timestamp and service provider timestamp can drift
1
saml.identity.provider.lifetime.ms

Default 60000000 (Optional)

  • Expiry time of IdP request (in milliseconds)
1
saml.identity.provider.nocert.rsa.key.strength

Default: 2048 (Optional)

  • The RSA key strength of the SAML certificate file
  • We recommend a minimum of 2048
1
saml.nameID.format

Default: transient (Optional)

  • Format the NameID from the service provider is expected in
  • 3forge supports the following:
    • email
    • unspecified
    • persistent
    • transient (default)