Welcome to our docs site. Docs on this site are for ACP version 9.
See these links for previous versions: Version 8, Version 7

Build a FSP Plugin

To configure a Platform for Identity Federation, you need to upload a Federation Service Provider (FSP) plugin that describes your external Identity Provider. The plugin is a packaged archive that includes a JSON-based configuration file with implementations for both WS-Fed or SAML2. This page describes how to build a FSP plugin including, plugin requirements and creating a JSON configuration file.

FSP Plugin Requirements

  • A configuration file named wsfed.json or saml.json (depending on the protocol you are using) that describes your external IdP

Apprenda has pre-built implementations of this archive available for you to use and customize for your enterprise environments. Contact your support representative for more details.

SAML Configuration Example

Below is an example external IdP description that uses SAML2. All HTTPS://MY.IPD.COM/* should be replaced with the real URL values to your IdP solution. Note that the URLs for the input values may be different depending on your IdP solution. For more information on the input values required, see the SAML plugin attribute definitions. The Platform will automatically replace $#ApprendaBaseAddress#$ with the value of your Platform URL, but you can replace it yourself with your Platform URL if you desire.

{
  "options": {
    "SPOptions": {
      "EntityId": "$#ApprendaBaseAddress#$",
      "SigningServiceCertificate": {
        "cert": ""
       }
    },
    "AuthenticationMode": "Active",
    "AuthenticationType": "HTTPS://MY.IDP.COM/*",
    "IdentityProviders": [
      {
        "EntityId": "HTTPS://MY.IDP.COM/*",
        "MetadataLocation": "HTTPS://MY.IDP.COM/*",
        "SingleSignOnServiceUrl": "HTTPS://MY.IDP.COM/*",
        "SingleLogoutServiceUrl": "HTTPS://MY.IDP.COM/*",
        "SingleLogoutServiceResponseUrl": "HTTPS://MY.IDP.COM/*",
        "ArtifactResolutionServiceUrls": {
          "0": "HTTPS://MY.IDP.COM/*"
        },
        "Binding": "HttpRedirect",
        "SingleLogoutServiceBinding": "HttpRedirect",
        "AllowUnsolicitedAuthnResponse": false,
        "OutboundSigningAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
        "WantAuthnRequestsSigned": false,
        "DisableOutboundLogoutRequests": false,
        "SigningKeys": [
          {
            "cert": ""
          }
        ]
      }
    ]
  },
  "claimsMappings": {
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": [ "http://saasgrid.apprenda.com/claims/emailAddress", "http://saasgrid.apprenda.com/claims/userAccount" ],
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": [ "http://saasgrid.apprenda.com/claims/displayName" ],
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/test": [ "http://saasgrid.apprenda.com/claims/description" ]
  },
  "staticClaims": {
  },
  "passThroughOriginalClaims": true
}

SAML Attributes

Use the following attributes to define your Identity Provider in a configuration file named saml.json in a FSP plugin package. Depending on your IdP configuration, you may not need all objects or attributes to describe how the Platform should interact with your IdP.

Authentication Type and Mode

{
  "options": {
    "AuthenticationMode": "Active",
    "AuthenticationType": "HTTPS://MY.IPD.COM/*"
  }
}
Attribute Description Type
AuthenticationMode Determines the authentication mode to use. If Active, the authentication middleware alter the request user coming in and alter 401 Unauthorized responses going out. If Passive, the authentication middleware will only provide identity and alter responses when explicitly indicated by the AuthenticationType String, supported values: Active, Passive
AuthenticationType A unique value to identify the external IdP. It recommended to use the URL of that IdP.  This value is also used for the IdP claim in the resulting tokens. String

Service Provider Options

Service provider (SP) options are contained in an object and describe how to access your Platform.

{
  "options": {
    "SPOptions": {
        "EntityId": "$#ApprendaBaseAddress#$",
        "SigningServiceCertificate": {
          "cert": ""
        }
    }
  }
}
Attribute Description Type
EntityId URI that defines the Relying Party to the Security Token Services. This should be the Platform URL where you are uploading the plugin. Use the $#ApprendaBaseAddress#$ token as the value if you want the Platform to insert the URL for you when the plugin is uploaded String

SigningServiceCertificate

The certificate the service provider users for signed requests

 Object

cert

 Value of the certificate String

Identity Providers

The IdentityProviders is an array of objects that describes where the Platform can retrieve information from your federation service.

{
  "options": {
    "IdentityProviders": [
      {
        "EntityId": "HTTPS://MY.IDP.COM/*",
        "MetadataLocation": "HTTPS://MY.IDP.COM/*",
        "SingleSignOnServiceUrl": "HTTPS://MY.IDP.COM/*",
        "SingleLogoutServiceUrl": "HTTPS://MY.IDP.COM/*",
        "SingleLogoutServiceResponseUrl": "HTTPS://MY.IDP.COM/*",
        "ArtifactResolutionServiceUrls": {
          "0": "HTTPS://MY.IDP.COM/*"
        },
        "Binding": "HttpRedirect",
        "SingleLogoutServiceBinding": "HttpRedirect",
        "AllowUnsolicitedAuthnResponse": false,
        "OutboundSigningAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
        "WantAuthnRequestsSigned": false,
        "DisableOutboundLogoutRequests": false,
        "SigningKeys": [
          {
            "cert": ""
          }
        ]
      }
    ]
  }
}
Attribute Description Type
AllowUnsolicitedAuthnResponse Determines if the Identity Providers allows unsolicited responses. If true, InResponseTo is not required and the Identity Provider can initiate the authentication process. If false, the InResponseTo attribute is required and the authentication process must be initiated by an AuthnRequest from the service provider. Boolean, true/false
ArtifactResolutionServiceUrls The endpoints on the Identity Provider point of contact server where artifacts are exchanged for SAML messages Array of endpoints
EntityId Issuer name that the Identity Provider uses when sending responses String
InResponseTrue Required if AllowUnsolicitedAuthnResponse is false. String
Binding The binding that the services provider should use when sending requests to the Identity Provider. One of the supported values of the Saml2BindingType enum. String, supported values: HttpRedirect, HttpPost, or Artifact
MetadataLocation URL to retrieve Federation metadata String
OutboundSigningAlgorithm Hashing algorithm used for signing claims String
SigningKeys Certificate the Identity Provider uses to sign its messages Array of certs
cert Value of the certificate String
SingleSignonServiceUrl URL where the Identity Provider listens for incoming sign on requests String
SingleLogoutServiceBinding The URL where the Identity Provider listens for incoming logout requests String
SingleLogoutServiceUrl URL where the Identity Provider listens for incoming logout requests String
SingleLogoutResponseServiceUrl URL where the Identity Provider listens for incoming logout responses String
WantAuthRequestsSigned Determines if authentication requests should be signed by the Service Provider Boolean, true/false

Claims

These attributes define claims to map and are optional, depending on the requirements of your IdP.

{
  "options": {

  },
  "claimsMappings": {
    "http://claimURL": [""]
  },
  "staticClaims": {
    "http://claimURL": [""]
  },
  "passThroughOriginalClaims": true
}
Attribute Description Type
Claims Mapping

Maps incoming claims to Apprenda User attributes

 Array claims to map
Static Claims Creates custom claim mappings Array of claims to map

Original Claims

 Passes claims that cannot be mapped to Apprenda attributes onto guest applications Boolean, True/False

WS-Fed Configuration Example

Below is an example external IdP description that uses WS-Fed. HTTPS://MY.IPD.COM/* represent where you should input the real URL values to your IdP solution, if the attribute is applicable to your IdP. Note that the URLs for the input values may be different depending on your IdP solution. For more information on the input values required, see the WS-fed plugin attribute definitions. The Platform will automatically replace $#ApprendaBaseAddress#$ with the value of your Platform URL, but you can replace it yourself with your Platform URL if you desire.

{

  "options": {
    "metadataAddress": "http://myidp.com/idp/wsfed/metadata",
    "wtrealm": "$#ApprendaBaseAddress#$",
    "backchannelTimeout": "00:01:00",
    "refreshOnIssuerKeyNotFound": true,
    "useTokenLifetime": true,
    "authenticationType": "https://my.idp.com",
    "configuration": {
      "tokenEndpoint": "https://myidp.com/idp/wsfed",
      "issuer": "https://myidp.com/idp",
      "signingKeys": [
        {
          "cert": ""
        }
      ]
    }
  },
  "claimsMappings": {
    "http://claimURL": [""]
  },
  "staticClaims": {
    "http://claimURL": [""]
  },
  "passThroughOriginalClaims": true
}

WS-Fed Attributes

Use the following attributes to define your Identity Provider in a configuration file named wsfed.json in a FSP plugin package. Depending on your IdP configuration, you may not need all objects or attributes to describe how the Platform should interact with your IdP.

{
  "options": {
    "metadataAddress": "http://myidp.com/idp/wsfed/metadata",
    "wtrealm": "$#ApprendaBaseAddress#$",
    "backchannelTimeout": "00:01:00",
    "refreshOnIssuerKeyNotFound": true,
    "useTokenLifetime": true,
    "authenticationType": "https://my.idp.com"
  }
}
Attribute Description Type
MetaDataAddress

URL to retrieve Federation metadata

 String
Wtrealm

URI that defines the Relying Party to the Security Token Services. This should be the Platform URL where you are uploading the plugin. Use the $#ApprendaBaseAddress#$ token as the value if you want the Platform to insert the URL for you when the plugin is uploaded

 String

BackChannelTimeout

  

Timeout value in milliseconds for back channel communications

 String

RefreshOnIssuerKeyNotFound

Boolean that determine if a metadata refresh is attempted after a Signature Key is not found. This allows for automatic recovery in the event of a signature key rollover

 Boolean, True/False
UseTokenLifetime

Boolean that determines if the authentication session lifetime (e.g. cookies) should match that of the authentication token. If the token does not provide lifetime information then normal session lifetimes are used

 Boolean, True/false

AuthenticationType

A unique value to identify the external Identity Provider. Its recommended to use the URL of the Identity Provider. This value is also used for the Identity Provider claim in the resulting tokens

  

Configuration

The token endpoint and issuer name that the Identity Provider uses when sending responses. If not provided, then one is created using the MetadataAddress and Backchannel properties.

{
  "options": {
    "configuration": {
      "tokenEndpoint": "https://myidp.com/idp/wsfed",
      "issuer": "https://myidp.com/idp",
      "signingKeys": [
        {
          "cert": ""
        }
      ]
    }
  }
}
Attribute Description Type
tokenEndpoint Endpoint to request tokens from String
issuer URI of the intended token issuer. Sets the base URL of WS-Federation sign-in requests and sign-out requests String
signingKeys Certificate the Identity Provider uses to sign its tokens Array of cert objects

Claims

These attributes define claims to map and are optional, depending on the requirements of your IdP.

{
  "options": {

  },
  "claimsMappings": {

    "http://claimURL": [ ""]
  },
  "staticClaims": {

    "http://claimURL": [ ""]
  },
  "passThroughOriginalClaims": true
}
Attribute Description Type
Claims Mapping

Maps incoming claims to Apprenda User attributes

 Array claims to map
Static Claims Creates custom claim mappings Array of claims to map

Original Claims

 Passes claims that cannot be mapped to Apprenda attributes onto guest applications Boolean, True/False