Configure OAuth or SAML authentication

This section explains how to configure integration for the two authentication protocols that the AppDirect platform supports for single sign-on (SSO): SAML and OpenID.

AppDirect supports SSO with SAML 1.0, 1.1, or 2.0, or OpenID 2.0, authentication. However, AppDirect strongly recommends that you use SAML because OpenID 2.0 is deprecated by many vendors (for example, Google).

To access the Edit Authentication page for both options, go to Products > locate the product that you want to configure > Edit > Edit Authentication.

AppDirect supports email addresses that include the + symbol. Ensure that your system accepts email assertion attributes that include any of the standard characters.

SAML authentication

AppDirect acts as a SAML identity provider to support single sign-on (SSO) for applications. To support SSO, applications need to act as a SAML service provider (and when they do, they also support SSO from other SAML identity providers, such as OneLogin, Ping Identity, and Okta).

AppDirect recommends using SAML version 2.0, however, AppDirect also supports SAML 1.0 and 1.1.

This section covers these steps to configure SSO authentication:

It also covers these topics:

Select a SAML library

Select a SAML-compliant library for your chosen SAML version (1.0, 1.1 or 2.0), and ensure it is compatible with your programming language. The AppDirect sample developer application on Github, and the OASIS SAML documentation can also be very useful. There are several libraries in all major languages, including these:

Configure SAML authentication

To configure SAML Authentication for SSO in the AppDirect user interface, follow this procedure.

Procedure

Step 1. Click Live Products > locate the product that you want to configure > Edit. The product configuration page opens.

Step 2. On the left menu, click Edit Authentication. The Edit Authentication page opens.

Step 3. Under Single Sign On, select SAML. The SAML configuration fields appear.

Step 4. From the SAML Version dropdown menu, select an SAML version.

AppDirect recommends using SAML version 2.0, but also supports SAML 1.0, and 1.1.

Step 5. Enter the Assertion Consumer Service URL.

When subscribed customers visit their MyApps page in AppDirect, and click the application tile to access your application, they are redirected to the configured Assertion Consumer Service URL, with a signed assertion of the user's identity.

Step 6. Enter the Service Provider / Audience Entity.

To validate requests arriving at your Assertion Consumer Service, your SAML library requires you to provide the SAML Identity Provider metadata, or certificate and identifier. For information about configuring this, see Service Provider / Audience Entity, in this section.

Step 7. From the Name ID Type drop-down list, select your preference.

The Name ID identifies users authenticating to your application. It can be specified in either of three types (formats):

  • Persistent (default)—Identifies users by an immutable identifier such as the AppDirect user.uuid, or an immutable userEntitlement.externalVendorIdentifier, that you provide when they are assigned your app.
  • Email—Identifies users by their email addresses, such as the AppDirect user’s.emailAddress.
  • Unspecified—Selected when neither the Persistent, nor Email, option is appropriate.

This format is declarative only. It is included in the assertions but it does not limit or define the values that you can specify in the Name ID.

Step 8. In Name ID, enter a Name ID value.

The Name ID value can be any value, and is normally a placeholder, such as:

  • {user.uuid} (default)
  • {userEntitlement.externalVendorIdentifier}
  • {user.emailAddress}

For additional options, see Placeholders, in this section.

Step 9. Under Assertion Attributes, for each one, enter the Name and Value.

Configure an unlimited number of attributes in the assertions (and add, remove or rename them, if required). To fully customize your assertions, you can use placeholders in the attribute values. For additional options, see Placeholders, in this section.

Service provider / Audience entity

To validate requests arriving at your Assertion Consumer Service, your SAML library requires you to provide the SAML Identity Provider metadata, or certificate and identifier. When customers purchase your application, the location of the SAML Identity Provider (IDP) metadata, or certificate and identifier, is sent to you via the SUBSCRIPTION_ORDER event as a samlldp link.

Below is an example of a subscription event, including the samlIdp link at the end. Some elements have been omitted for brevity. For more information, see Subscription Order Events.

{
   "type": "SUBSCRIPTION_ORDER",
   "marketplace": {
       "partner": "APPDIRECT",
       "baseUrl": "https://www.appdirect.com"
   },
   "payload": {
       "company": {
           "uuid": "d27da41d-af43-42ab-8fed-fbc120f51f7e",
           "name": "Buyer's Company",
           ...
       },
       "order": {
           "editionCode":"FREE",
           "pricingDuration":"MONTHLY",
           ...
       },
       ...
   },
   ...
   "links": [{
           "rel": "samlIdp",
           "href": "https://www.appdirect.com/api/account/v2/subscriptions/6dc36823-30fe-4460-88a1-fb8b98e24cc0/saml"
       }]
}

If requested in JSON format (add the header Accept: application/json or appending .json to the link url), the IDP information returned looks similar to the following example:

{
   "uuid": "unique.random.uuid",
   "idpIdentifier": "https://your.subscription.generated.identity.provider.unique.random.identifier",
   "assertionConsumerServiceUrl": "https://your.assertion.consumer.url",
   "audienceUrl": "https://your.audience.entity.id",
   "relayState": "",
   "nameIdType": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
   "authenticationContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
   "notBeforeMinutes": null,
   "notAfterMinutes": null,
   "attributes": {},
   "certificate": {
       "uuid": "unique.random.uuid",
       "publicCertificate": "-----BEGIN CERTIFICATE-----\nMII.....\n-----END CERTIFICATE-----\n",
       "publicKey": "-----BEGIN PUBLIC KEY-----\nMII.....\n-----END PUBLIC KEY-----\n",
       "fingerprint": "C0:99:43:2C:08:2C:24:6E:70...",
       "expirationDate": 1234567890
   }
}

You can obtain similar information in the standard SAML metadata format by requesting it with Accept: application/samlmetadata+xml or appending .samlmetadata.xml to the link URL. The metadata includes the IDP login URL, initiated by your service provider, to which login requests are sent.

Placeholders

Placeholders can be used with Name ID, and Attribute Values. The following placeholders are supported:

  • {marketplace.url}—Marketplace in which the subscription resides
  • {company.uuid}—UUID of the company in AppDirect
  • {company.name}—Company name
  • {companyEntitlement.uuid}—UUID of the subscription in AppDirect
  • {companyEntitlement.externalVendorIdentifier}—Identifier optionally provided by your application when the subscription was purchased
  • {user.uuid}—UUID of the user in AppDirect
  • {user.emailAddress}—Email address of the user
  • {user.firstName}—First name of the user
  • {user.lastName}—Last name of the user
  • {user.language}—User language in IETF BCP 47 format. E.g: en-UK
  • {userEntitlement.externalVendorIdentifier}—Identifier optionally provided by your application when the user was assigned to the subscription

OpenID authentication

AppDirect acts as an OpenID 2.0 provider to support single sign-on (SSO) for applications. To support SSO, applications need to act as OpenID consumers.

This section covers these tasks, which are required to configure SSO with OpenID 2.0:

There is also information regarding the following topics:

Select an OpenID library

Select an OpenID 2.0-compliant library compatible with your programming language. For a good resource of basic information, see the Getting Started Guide published by OpenID.net.

There are dozens of OpenID libraries available, in all major languages. This is some of them:

  • OpenId4Java
  • PHP OpenID Library
  • LightOpenID (PHP)
  • Python OpenID Library
  • Ruby OpenID Library
  • DotNetOpenAuth

An implementation provided by a third-party, such as JanRain, is also acceptable.

Configure OpenID authentication

To configure OpenID authentication, follow this procedure.

Procedure

Step 1. Click Live > Products > locate the product that you want to configure > Edit. The product configuration page opens.

Step 2. On the left menu, click Edit Authentication. The Edit Authentication page opens.

Step 3. Under Single Sign On, select OpenID > enter the Login URL

For information about the Login URL configuration, and the required format, see Login URL, in this section.

Step 4. Enter the OpenID Realm

For information about the OpenID Realm configuration, and the required format, see OpenID Realm, in this section.

Step 5. Click Save. A confirmation message appears.

You are now ready to configure the OpenID provider endpoint requests. This configuration occurs outside of AppDirect. See Configure OpenID provider endpoint requests, in this section.

Login URL

When subscribed customers visit their MyApps page in AppDirect, and click the application tile to access your application, they are redirected to an OpenID Login Endpoint URL. At that URL, you, the developer, initiate the OpenID authentication request on your side, to support SSO with AppDirect for them. For information about the URL format, see Login and Realm Template Fields, in this section.

For the configuration procedure, see Configure OpenID authentication, in this section.

OpenID Realm

It is recommended that you use an OpenID realm, however, it is optional. An OpenID realm is a user-friendly way to manage authentication requests from unknown consumers during a single sign-on workflow.

Without an OpenID Realm configured, when an authentication request is received from an unknown consumer, AppDirect displays a confirmation message asking them if they want to log on to your application. If you configure an OpenID Realm, and add it to the whitelist, this manual approval every time the consumer wants to access your application can be bypassed.

In most cases, the realm URL for your application is identical to the login URL or may have an optional '*' wildcard character. However, if you delegate OpenID handling to a third party, it may be necessary to specify a different domain in the realm. Here are some examples:

  • When a login URL is https://example.com/login/{openId}, the OpenID realm could be https://example.com/login/*.
  • When a login URL is https://{openId}.example.com/login, the OpenID realm could be  https://*.example.com/login.

For information about the URL format, see Login and Realm Template Fields, in this section.

For the OpenID Realm configuration procedure, see Configure OpenID authentication, in this section.

OpenID template fields

When you format the login URL and realms, use the following template fields:

  • {openid} template field—Required. It is populated with a user's unique OpenID URL, which they need to initiate the OpenID process.
  • {accountIdentifier} template field—Optional. It is populated with the unique account identifier provided by you, the developer, during a subscription order.

These are URL template examples:

  • https://example.com/login?openid_url={openid}
  • https://{accountIdentifier}.example.com/login?openid_identifier={openid}
  • https://example.com/login/openid={openid}&accountId={accountIdentifier}

Configure OpenID provider endpoint requests

Prepare your systems to integrate with the AppDirect provider endpoint.

After a user is redirected to the configured OpenID login URL, you send discovery requests to the OpenID provider running on one of the AppDirect-powered marketplaces, as passed in the {openid} template field. This OpenID provider URL looks similar to this: https://www.acme-marketplace.com/openid/id.

At this point, you typically only need to use the AppDirect endpoint with an OpenID 2.0-compliant library to perform the OpenID authentication flow with the user. Many libraries have a sample with a form field for the user to enter an OpenID URL. Developer endpoints can fill that field with the URL received in the {openid} template field, and submit the form to initiate an OpenID authentication request automatically.

Test OpenID with AppDirect

Users with AppDirect accounts can use the AppDirect OpenID endpoint URL to log on to any OpenID-relying party that supports OpenID "identifier select.”

Note: This is not a unique, per user identifier for OpenID "directed identity." The AppDirect OpenID endpoint supports OpenID "identifier select," which allows consumers to provide one site-wide identifier, and returns a specific user identifier.

With your AppDirect account, test the AppDirect endpoint on sites such as Test-id.org or Plaxo. To test your integration endpoint, you can try using the AppDirect OpenID endpoint or any other OpenID 2.0-compliant provider.

Simple registration and attribute exchange

You can read some additional user attributes through Simple Registration (SREG), and Attribute Exchange (AX), fields. Both SREG and AX fields may be requested during a user's OpenID login.

The following OpenID Attribute Exchange fields are supported:

  • User UUID—https://www.appdirect.com/schema/user/uuid
  • Email address—http://axschema.org/contact/email
  • First name—http://axschema.org/namePerson/first
  • Last name—http://axschema.org/namePerson/last
  • Full name—http://axschema.org/namePerson
  • Language—http://axschema.org/pref/language
  • Company UUID—https://www.appdirect.com/schema/company/uuid
  • Company name—http://axschema.org/company/name
  • Company title/position—http://axschema.org/company/title

The following OpenID Simple Registration fields are supported:

  • Email address
  • Email address: http://axschema.org/contact/email
  • Full name
  • Nickname

Support for additional SREG and AX fields such as country, timezone, date of birth, and language is added in the future.

Logging out of your application

After AppDirect users sign out of your application, the developer should redirect them to the URL <base marketplace URL>/applogout?openid=<the OpenID of the user logging out>.

ModSecurity

The OpenID protocol may pass encoded URLs as query string parameters, which may trigger false positives for the ModSecurity web application firewall. ModSecurity rules 1234234, and 340153, are commonly the cause. The OpenID return URL may need to be excluded from these rules.