Configuring App Builder as an identity provider¶

App Builder can serve as both a SAML Service Provider (SP) and as a SAML Identity Provider (IdP). This allows one instance of Viny (the IdP) to authenticate users on behalf of another instance (the SP).

There are four main tasks involved:

1. Generate a signing certificate.
2. Create a SAML IdP security provider.
3. Create a SAML SP security provider.
4. Test

These instructions make the following assumptions:

1. You have at least two instances of App Builder.
2. You have administrator access to each App Builder instance.

The instructions below will refer to the following properties:

Generate a signing certificate¶

In SAML Single Sign-On (SSO), trust is established via signing certificates. The process for acquiring a certificate is outside the scope of this document. However, for illustrative purposes, the following commands demonstrate how to generate a compatible certificate using the OpenSSL command-line utility.

The following command generates a PEM-encoded private key (key.pem) and self-signed certificate (cert.pem):

$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 1095 -subj "/CN=idp.example.com/O=App BuilderIdP"

You will need the contents of the cert.pem file to configure the App Builder SP security provider.

The following command generates a PKCS#12 archive (cert.pfx) containing both the private key and certificate:

$ openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx

You will be prompted to provide a password. You will need the password to configure the App Builder IdP security provider.

Finally, the following command base64-encodes the PKCS#12 archive:

$ openssl base64 -in cert.pfx -out cert.txt -A

You will need the contents of the cert.txt file to configure the App Builder IdP security provider.

Create a SAML IdP security provider¶

To create a SAML IdP security provider, start by signing into the instance of App Builder which will serve as the IdP.

1. Navigate to the IDE
2. Click the Security Providers button
3. In the User Authentication panel, click the + User Authentication button

4. Provide the following:

   • Name: IdP Security Provider Name, e.g. App BuilderIdP
   • Type: SAML Identity Provider

5. Click the Save button

6. In the Properties panel, click the + Property button to add each of the following properties:

   • AssertionConsumerService: Assertion Consumer Service URL, e.g. https://sp.example.com/App Builder/signin-App BuilderSP.
   • Audience: App Builder SP URL, e.g. https://sp.example.com/App Builder/.
   • Issuer: App Builder IdP URL, e.g. https://idp.example.com/App Builder/.
   • Recipient: Assertion Consumer Service URL, e.g. https://sp.example.com/App Builder/signin-App BuilderSP.
   • SigningCertificate: base64-encoded, PKCS#12 archive (see Generate a Signing Certificate).
   • SigningCertificatePassword: Signing certificate password (see Generate a Signing Certificate).

7. In the Claims panel, click the + Claim button to map each of the following properties:

   • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   • Group: http://schemas.xmlsoap.org/claims/Group

8. In the Provider panel, click the Edit button

9. Check the Enabled option
10. Click the Save button

The steps above include a group claim. The group claim is used to pass group membership to the SP. However, groups are not passed by default. To pass a group, you must add it to the IdP security provider. For example:

1. Navigate to the IDE
2. Click the User Management button
3. Click the Identities button
4. Select the IdP security provider, e.g. App BuilderIdP
5. In the Provider Groups panel, click the + Group button
6. Provide a Name, e.g. Administrators
7. Select the Group, e.g. Administrators
8. Click the Save button

Create a SAML SP security provider¶

To create a SAML SP security provider, start by signing into the instance of App Builder which will serve as the SP.

1. Navigate to the IDE
2. Click the Security Providers button
3. In the User Authentication panel, click the + User Authentication button

4. Provide the following:

   • Name: SP Security Provider Name, e.g. App BuilderSP.
   • Type: SAML
   • User Provisioning: Check to enable user provisioning.
   • Show On Login Form: Check to show the authentication provider on the login form.

5. Click the Save button

6. In the Properties panel, click the + Property button to add each of the following properties:

   • Audience: App Builder SP URL, e.g. https://sp.example.com/App Builder/.
   • Issuer: App Builder IdP URL, e.g. https://idp.example.com/App Builder/.
   • Recipient: Assertion Consumer Service URL, e.g. https://sp.example.com/App Builder/signin-App BuilderSP.
   • RequestRedirectEndpoint: Request Redirect Endpoint, e.g. https://idp.example.com/App Builder/signin-App BuilderIdP.
   • SigningCertificate: PEM-encoded certificate (see Generate a Signing Certificate).

7. In the Claims panel, click the + Claim button to map each of the following properties:

   • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   • Group: http://schemas.xmlsoap.org/claims/Group

8. In the Provider panel, click the Edit button

9. Check the Enabled option
10. Click the Save button

The steps above include a group claim. The group claim is used to map claims to security provider groups. However, security provider groups are not mapped to App Builder security groups by default. To map a security provider group to an App Builder security group:

1. Navigate to the IDE
2. Click the User Management button
3. Click the Identities button
4. Select the SP security provider, e.g. App BuilderSP
5. In the Provider Groups panel, click the + Group button
6. Provide a Name, e.g. Administrators
7. Select the Group, e.g. Administrators
8. Click the Save button

Test¶

To test, start by launching a browser in Incognito/Private mode.

1. Navigate to the App Builder SP URL, e.g. https://sp.example.com/App Builder/.
2. On the login form, click the option to sign in with the App Builder SP, e.g. App BuilderSP. You will be redirected to the App Builder IdP login form.
3. Sign into the App Builder IdP instance. You will be redirected back to the App Builder SP.

If the test was successful, you will be signed into the App Builder SP instance.

Troubleshooting¶

"sign in with..." option missing from the login form¶

If the "Sign in with..." option is missing from the login form, the App Builder SP security provider is either not enabled or the Show On Login Form option was not checked.

404 not found error after clicking "sign in with..."¶

If you receive a 404 Not Found error after clicking "Sign in with..." button on the login form, this may indicate that the App Builder IdP Security Provider is not enabled, is misnamed or is improperly configured. To prevent service disruption, App Builder will disable the security provider at runtime if it detects a misconfiguration.