Ceptor - Get a Free Trial

Federation - SAML / WebSSO

Owned by Kim Rasmussen
Last updated: Oct 14, 2023
11 min read

Here, you can specify general settings for SAML federations

Federations

SAML Configuration

This is kept in the root of the federations JSON object.

Max Time Difference

Maximum acceptable time difference in minutes - allows for clock skew between issuer and service provider.

Default: 2
JSON key is websso.samlsigning.maxtimedifference.minutes

Authentication Methods

List separated by semicolon - list of names to use for authention methods in SAML document - e.g. 6=LDAP;42=NemID;43=SMS OTP  - If not mapped to another name, the value for authmethod attribute/claim is the plugin ID of the authentication method used to authenticate the user.

Default: None
JSON key is websso.samlsigning.maxtimedifference.minutes

HTTP Proxy configuration

This is kept in a JSON object called proxy. Note that this configuration is shared with the OpenID Connect / JWT Federation configuration.

Enabled

Check to enable HTTP proxy.

Default: false
JSON key is enabled

Hostname

Maximum acceptable time difference in minutes - allows for clock skew between issuer and service provider.

Default: 2
JSON key is host

Port

TCP Port number of proxy server

Default: 8080
JSON key is port

Userid

Userid to authenticate to proxy server.

Default: None
JSON key is user

Password

Password needed to authenticate to proxy server - can be encrypted, see Encrypting or Obfuscating Passwords

Default: None
JSON key is password

No Proxy For

Hostname matching this pattern will not be proxied

Default: None
JSON key is noproxyfor


SAML Service Providers

SAML / WebSSO Service Provider configuration

This is kept in the federation root as a JSON array called saml.serviceproviders.

Service Providers

SAML / WebSSO Service Providers - any service provider you wish to issue SAML tickets to should be configured here.

Default: None
JSON key is saml.serviceproviders - each service provider is a separate JSON object within this  array.

SAML / WebSSO Service Provider

Each SAML Service provider is a separate JSON object within the JSON Array saml.serviceproviders

SAML / WebSSO Service Provider

Name

Unique name of SAML Service Provider - this is the name that this  provider is known under as referenced from Ceptor Gateway in the SAML/ADFS/WebSSO Authentication section -see the property "Service Provider Name"

Default: None
JSON key is name

Display Name

Display name - this name can be used in presentation to users if they need to choose between providers.

Default: None
JSON key is display.name

Description

Here, you can enter a description of the service provider - the description itself is not actively used anywhere, so it is just for informational purposes.

Default: None
JSON key is description

URL

Service Provider URL - this is the URL that the login response ticket is sent to.

Default: None
JSON key is url

Issuer

Issuer name - this name is seen by the Service Provider as the issuer of the SAML ticket.

Default: Ceptor
JSON key is issuer

Audience

Audience - if not set, defaults to URL. This will be added as audience in the SAML Response ticket.

Default: URL
JSON key is audience

Identifiers

List of valid identifiers for this service provider.

When a SAML Request is received, it contains an issuer - this issuer is matched up against the defined identifiers, and the first configured service provider that matches, if any is picked. Note that multiple identifiers can be configured.

Default: None
JSON key is identifiers (containing a JSON Array of strings)

Role Pattern

When adding the role/groups attribute to a SAML ticket, only groups matching this pattern will be included.

Refer to description of wildcards/regex patterns here: Locations - Conditions


Default: *
JSON key is role.pattern

Attributes

Attributes to send as claims to Service Provider.

See SAML / JWT Attributes / Claims for information of content.

Default: None
JSON key is attributes - must be a JSON Array of Strings, each in format name=value

IDP Metadata Template

This contains the template for federation metadata.

In this template, you can define the SAML 2.0 Identity Provider Metadata Template - see here: Ceptor Gateway - Authentication - SAML/ADFS/WebSSO how to retrieve this metadata at runtime - using this template make it possible to provide an URL where the service provider can periodically retrieve the SAML Identity Provider Federation metadata from.

This metadata contains information about certificates needed to verify the signature, the macros %{signcert} and %{encryptcert} are replaced with the actual certificates loaded from the keystores.

Do not forget to adjust the information within to match your scenario.

You can find all the details you never wanted to know about federation metadata here: https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf or a simplified overview here: https://www.oasis-open.org/committees/download.php/51890/SAML%20MD%20simplified%20overview.pdf

For most integrations, the example will be enough for the Service Provider to retrieve fields he needs, mainly the certificates.


Default: None
JSON key is identityprovider.metadata

SAML Response Script

In order to be able to modify all aspects of a SAML response before it is signed, it is possible to specify a SAML Response script that is executed immediately after generating the SAML response string, but before it is signed.

It can optionally return a modified string containing a customized SAML response, which will then be signed and returned.

The documentation in Ceptor Console when editing the script contains an example script written in Groovy that adds an additional Attribute to the SAML response before it is signed.

When the script is called, it has these variables available:

  • samlversion - 1 or 2 depending on which SAML type response is being generated
  • context - Script context, with additional attributes about the user context available - see below
  • input - SAML Response about to be created - can be modified and returned.

The context looks like the following:

Context
public class ScriptContext {
	/** Session Controller */
	public PTSServer sessionController;

	/** Configuration for session controller and authentication plugins */
	public Properties configuration;

	/** Session we are generating SAML responses for */
	public User session;

	/** SAML request as string, or null if no request present */
	public String samlRequest;

	/** Parsed SAML Request, or null if not present */
	public ADFSSamlRequest parsedSaml;

	/** Service Provider entry */
	public ADFSSamlSSOAuthPlugin.ServiceProviderEntry sp;
}

The context.parsedSaml attribute above has these values available:


public static class ADFSSamlRequest {
	public boolean saml2;
	public String issueInstant;
	public String requestID;
		
	// SAML 2
	public String issuer;
	public String destination;
}


Default: None
JSON key is saml.response.script

Keystore

The keystore is configured in a JSON object called keystore within the service provider's JSON object.

Key or certificate configuration

JCE Provider

Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.

Default: None
JSON key is provider

Keystore type

Keystore type, usually PKCS12 or JKS

Default: PKCS12
JSON key is type

Filename

Name of file to load keystore from - note that some keystores, e.g. Luna does not have a file

Default: None
JSON key is file

Password

Password for the keystore - can be encrypted, see Encrypting or Obfuscating Passwords

Default: None
JSON key is password

Password per alias

This is only needed if you have specific aliases in your keystore which have passwords that differ from the main keystore password - it allows you to specify a password for each alias specifically.

Default: None
JSON key is password.per.alias - this is a JSON Array with the format alias=password

Alias of private key

If provided, only the private key with the specified alias will be loaded.

Default: None
JSON key is alias.privkey

Alias of certificate

If provided, only the certificate with the specified alias will be loaded

Default: None
JSON key is alias.cert

Private key

Allows you to provide the private key as an RSA key in PKCS#8 format by pasting it directly.

Default: None
JSON key is privatekey

Certificate

Allows you to provide the certificate as Base64 encoded DER by pasting it directly instead of loading it from a keystore.

Default: None
JSON key is certificate


See also Keystore configuration for additional details of configuring keystores when using federation.

SAML Identity Providers

SAML / WebSSO Identity Provider configuration

This is kept in the federation root as a JSON array called saml.identityproviders.

Identity Providers

SAML / WebSSO Identity Providers - any identity provider you wish to be able to receive SAML Reponses from must be configured here.

Default: None
JSON key is saml.identityproviders - each identity provider is a separate JSON object within this  array.

SAML / WebSSO Identity Provider

Name

Unique name of SAML Identity Provider.
This is the name that this  provider is known under as referenced from Ceptor Gateway in the SAML/ADFS/WebSSO Authentication section -see the property "Identity Provider Name"

Default: None
JSON key is name

Display Name

Display name - this name can be used in presentation to users if they need to choose between providers.

Default: None
JSON key is display.name

Description

Here, you can enter a description of the identity provider - the description itself is not actively used anywhere, so it is just for informational purposes.

Default: None
JSON key is description

SAML Identifier

Enter SAML Identifier - defaults to Identity Provider Name if not entered.
This identifier is used in the wtrealm=  parameter when redirecting to the identity provider to sign in.


Default: Identity Provider Name
JSON key is identifier

Audience

If specified, the audience in the received SAML response must match this pattern - wildcards can be used, and if not set, audience validation is not done.

Default: None
JSON key is expected.audience.pattern

Use subject as userid

If true, subject  from SAML response, if present, is used as userid.

Default: None
JSON key is subject.as.userid

Userid Attribute Name

Semicolon separated list of attribute names - the first match will be used as userid if such an attribute is provided in the SAML response.

Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn;upn
JSON key is userid.attribute.name

Username Attribute Name

Semicolon separated list of attribute names - the first match will be used as username if such an attribute is provided in the SAML response.

Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name;name
JSON key is username.attribute.name

Role Attribute Name

Semicolon separated list of attribute names - the first match will be used as user groups if such an attribute is provided in the SAML response.

Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role;role
JSON key is role.attribute.name

Role Pattern

Provided user groups must match this pattern, or they are ignored.

Default: None
JSON key is role.pattern

Attributes to store

Pattern for deciding which attributes to copy from the SAML response into the session.

Default: *
JSON key is attributes.to.store.in.session

URL

URL to identity provider.

If Ceptor Gateway redirects the user to the identity provider to ask for signin, it will use this URL, but add these query parameters to it:
?wa=wsignin1.0&id=passive&wtrealm=<SAML identifier>&wreply=<Return URL>&wct=<Timestamp> 

Default: None
JSON key is url

Known IPs

List of known IP adresses (separate with semicolon). This list can be used by applications or gateway to automatically redirect to specific Identity Providers if the client uses a matching IP address.

Default: None
JSON key is known.ip.list

Metadata URL

SAML2 Identity Provider Federation Metadata - if specified, it is retrieved online from the Identity Provider - the keys/certificates present in the metadata will be used for validating the SAML response instead of having to configure certificates manually.

Default: None
JSON key is metadata.url

Metadata update interval

Number of minutes between refreshing the metadata from the metdata URL if specified.

Default: 120
JSON key is metadata.update.interval.minutes

Metadata

If metadata cannot be retrieved from online, it can instead be pasted here.

Default: None
JSON key is metadata

SP Metadata Template

Template for  providing Service Provider Metadata to Identity Provider.

%{signcert} will be replaced with the signing certificate, and %{encryptcert} will be replaced with the encryption certificate.

The encryption certificate is optionally loaded from the Keystore configuration.

Default: None
JSON key is serviceprovider.metadata

SAML Request Template

This is a template for how the generated SAML Request should look - remember to modify URLs to match your scenario.

Default: None
JSON key is samlrequest

Keystore

The keystore is configured in a JSON object called keystore within the identity provider's JSON object.

Key or certificate configuration

JCE Provider

Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.

Default: None
JSON key is provider

Keystore type

Keystore type, usually PKCS12 or JKS

Default: PKCS12
JSON key is type

Filename

Name of file to load keystore from - note that some keystores, e.g. Luna does not have a file

Default: None
JSON key is file

Password

Password for the keystore - can be encrypted, see Encrypting or Obfuscating Passwords

Default: None
JSON key is password

Password per alias

This is only needed if you have specific aliases in your keystore which have passwords that differ from the main keystore password - it allows you to specify a password for each alias specifically.

Default: None
JSON key is password.per.alias - this is a JSON Array with the format alias=password

Alias of private key

If provided, only the private key with the specified alias will be loaded.

Default: None
JSON key is alias.privkey

Alias of certificate

If provided, only the certificate with the specified alias will be loaded

Default: None
JSON key is alias.cert

Private key

Allows you to provide the private key as an RSA key in PKCS#8 format by pasting it directly.

Default: None
JSON key is privatekey

Certificate

Allows you to provide the certificate as Base64 encoded DER by pasting it directly instead of loading it from a keystore.

Default: None
JSON key is certificate


See also Keystore configuration for additional details of configuring keystores when using federation.

Signer Certificates

This configuration is stored in the JSON Object signer.certificates inside the identity provider JSON.

Additional Signer Certificates

JCE Provider

Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.

Default: None
JSON key is provider

Certificates

Provide a list of filenames or certificates directly within the configuration.

This allows you to specify additional trusted signer certificates for use when validating signed SAML Response - note that if you already are loading federation metadata from online, or have it pasted, these certificates configured here are in addition to the ones from the metadata.

Default: None
JSON key is certificates - which is a JSON Array of strings, each containing a filename of a certificate in .cer (binary or base64 encoded), .der or .p7b format or the certificate itself, if starting with -----BEGIN CERTIFICATE-----


See also Keystore configuration for additional details of configuring keystores when using federation.


Encryption Certificate

This configuration is stored in the JSON Object encryption.certificates inside the identity provider JSON.

Encryption Certificate

JCE Provider

Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.

Default: None
JSON key is provider

Certificates

If you wish to specify an encryption certificate for use when encrypting a SAML request, you can do so here - normally you would use federation metadata for this, but it can be specified manually.

Default: None
JSON key is certificate

SSL

This configuration is stored in the JSON Object ssl inside the identity provider JSON.

SSL/TLS related configuration when loading metadata

Verify server SSL certificate

Uncheck to disable SSL server certificate validation - if checked, SSL server certificates must either match installed root certificates in the JVM, or one of the additionally specified certificates.

Default: true
JSON key is verify.server.cert

Verify server SSL hostname

Uncheck to disable SSL hostname verification - if checked, the SSL hostname is matched up against the SSL server certificate.

Default: true
JSON key is verify.hostname

JCE Provider

Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.

Default: None
JSON key is provider - inside accepted.certificates JSON object within the ssl object.

Certificates

Provide a list of filenames or certificates directly within the configuration.

This allows you to specify additional SSL server issuer trust certificates certificates for use when validating signed SSL server certificate when retrieving metadata from remote

Default: None
JSON key is certificates- inside accepted.certificates JSON object within the ssl object.


© Ceptor ApS. All Rights Reserved.