Configuring Single Sign-On (SSO)

The service admin can configure SSO for their ProtoPie Enterprise environment.

With SSO, members can access ProtoPie through an authentication source of choice, e.g., Okta, Auth0, or OneLogin. These are also known as identity providers (IdP). This way, companies can centralize providing access to ProtoPie Enterprise.

SSO is an authentication scheme allowing users to log in to applications and websites with a single set of credentials—without having to manage multiple usernames and passwords. Many organizations and enterprises already included SSO in their internal policies to ensure security and convenience.

ProtoPie Enterprise supports two SSO protocols:

• SAML 2.0
• OpenID Connect (OIDC) – on top of OAuth 2.0

Setting Up SAML SSO

In SAML terminology, ProtoPie is the service provider (SP) that has to communicate with your identity provider (IdP) for authentication.

To set this up, add ProtoPie to your IdP. This comes down to: enter the assertion consumer service URL (spAcsUrl) from ProtoPie in your IdP, and the IdP Metadata URL from your IdP in ProtoPie.

1. Go to Authentication in the Service Admin Settings.
2. Enable SAML.
3. Copy the assertion consumer URL.

How you add applications to your IdP differs per IdP. We outlined the steps for using Okta below.

SAML SSO with Okta

Follow this easy step-by-step video tutorial from ProtoPie School to set up Single Sign-On (SSO) with Okta.

• Setting up SAML SSO with Okta.

Alternatively, you can follow the instructions below:

1. Log in to Okta and go to the Applications page.
2. Click on the Add Application in the top left corner.
   
   
3. Click on Create New App in the top right corner.
   
   
4. Select SAML 2.0 as the Sign on method and click on Create.
   
   
5. Enter ProtoPie as the app name under General Settings. For convenience, upload the ProtoPie logo. Then click on Next.
   
   
6. Do the following regarding the SAML Settings.
   1. Paste the copied assertion consumer URL in both the Single sign on URL and Audience URI (SP Entity ID) fields.
   2. Select EmailAddress as the Name ID format.
   3. Enter firstName for the Name, and user.firstName for the Value. Then, click on Add Another.
   4. Enter lastName for the Name, and user.lastName for the Value.
   5. Click on Next.
      
      
7. Select I'm a software vendor. I'd like to integrate my app with Okta and click on Finish.
   
   
8. Assign users in the ProtoPie app in Okta. Go to the ProtoPie application, and click on the Assignments tab. Assign users by clicking on the Assign button.
   
   
9. Click on the Sign On tab and then on View Setup Instructions.
   
   
10. The Identity Provider Single Sign-On URL is basically the IdP Metadata URL you need. Copy this.
    
    
11. Go back to Authentication in the Service Admin Settings.
12. If you didn't already, enable SAML.
13. Paste the IdP Metadata URL you copied in your IdP.
14. Click on Update.

SAML SSO with Another IdP

To set up SAML SSO with another IdP, as with Okta, use the assertion consumer service URL (spAcsUrl) from ProtoPie and IdP Metadata URL from your IdP. Refer to the documentation of your preferred IdP on how to add new applications.

SAML SSO with Azure AD

1. Sign in to Azure and access Azure Active Directory.

2. Select Enterprise applications on the left.

3. Select All applications → New application.

4. In Azure AD Gallery, search and select Azure AD SAML Toolkit to add it.

• In the Name field, enter ProtoPie. Additionally, you can choose to upload the ProtoPie logo.

5. Once the Application is added, you can check the Overview of the added Application as follows. Then you can finalize the settings in the Getting Started menu.

6. Select the Assign users and groups menu to set users or user groups.

7. Select the Set up single sign-on menu to begin the configuration of SSO. Select SAML method.

8. Select Basic SAML Configuration Edit to enter the values. Enter the following values.

• Identifier (Entity ID): https://PROTOPIE_DOMAIN/sp
• Reply URL (Assertion Consumer Service URL): https://PROTOPIE_DOMAIN/api/auth/callback/sso/saml
  • These values are the same as those from ProtoPie Admin Dashboard → Authentication → SAML → Assertion Consumer URL.
• Sign on URL: https://PROTOPIE_DOMAIN/api/auth/login/sso/saml

9. Copy the App Federation Metadata URL found in the SAML Signing Certificate.

10. Go to Authentication → SAML menu in ProtoPie Admin Dashboard to enable SAML and enter the following values:

• Authn Context: urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
• IdP URL (IdP Metadata URL): Enter App Federation Metadata URL you copied from above.

Setting Up OIDC SSO

OpenID Connect (OIDC) is an authentication protocol built on top of the OAuth 2.0 framework.

Follow this easy step-by-step video tutorial from ProtoPie School to set up OIDC SSO.

• Setting up OIDC SSO

Alternatively, you can follow the instructions below.

To set this up, add ProtoPie to your IdP. This comes down to: enter the callback URL (loginUrl) from ProtoPie in your IdP, and the authorization URL, token URL, client ID, and client secret from your IdP in ProtoPie.

1. Go to Authentication in the Service Admin Settings.
2. Enable OIDC.
3. Copy the callback URL.
   
   

How you add applications to your IdP differs per IdP. We outlined the steps for using Okta below.

OIDC SSO with Okta

1. Log in to Okta and go to the Applications page.
2. Click on the Add Application in the top left corner.
   
   
3. Click on Create New App in the top right corner.
   
   
4. Select OpenID Connect as the Sign on method and click on Create.
   
   
5. Enter ProtoPie as the app name under General Settings. For convenience, upload the ProtoPie logo. Also, paste the copied callback URL in the Login redirect URIs field. Then click on Save.
   
   
6. Assign users in the ProtoPie app in Okta. Go to the ProtoPie application, and click on the Assignments tab. Assign users by clicking on the Assign button.
   
   
7. Click on the General tab. Copy both: client ID and client secret.
   
   
8. Click on the Sign On tab. You need both the Authorization URL and Token URL. These two URLs do differ per IdP. For Okta, the Authorization URL has ${baseUrl}/oauth2/v1/authorize structure and the Token URL has ${baseUrl}/oauth2/v1/token structure. Use Issuer under the OpenID Connect ID Token for the base URL. Learn more about how to compose your base URL.
   
   
9. Go back to Authentication in the Service Admin Settings.
10. If you didn't already, enable OIDC.
11. Enter the authorization URL, token URL, client ID, and client secret.
12. Click on Update.

OIDC SSO with Another IdP

To set up OIDC SSO with another IdP, as with Okta, you need the Callback URL from ProtoPie, and the Authorization URL, Token URL, Client ID, and Client Secret from your IdP. Refer to the documentation of your preferred IdP on how to add new applications.

Managing Members

With SSO enabled, still manage your members in ProtoPie Enterprise itself. Even though you add or remove users in your IdP, ProtoPie Enterprise does not reflect these changes automatically.

If you change a user's email address in the IdP, make the same change in ProtoPie Enterprise.

FAQs

• Can I use only Single Sign-on (SSO) instead of Email & Password?

  If you want, you can use one of two verification methods. However, you cannot disable all the verification methods. At least one verification method, Email & Password or SSO, needs to be enabled.

  In order to enable the SSO verification method only, the service admin, whose configuration is to be changed, needs to be SSO log-in enabled. In the case of service admin set in the Email & Password method as its initial system configuration, please refer to the procedure below.

  1. Invite a new user who is to be set as a service admin.
  2. The user signs up by the SSO verification method.
  3. The invited user is designated as the service admin.
  4. After log-in, the user disables the Email & Password verification method.
  5. (Optional) change the existing service admin role to a member.

• Do I need to use IdP, not ProtoPie Enterprise, for member management?

  No, you don’t. Even if you add or remove a user in IdP, it is not automatically reflected on ProtoPie Enterprise.

• Can I log into ProtoPie if I change my email address in IdP?

  The user is recognized as the same user only when the registered email address in both IdP and ProtoPie Enterprise are the same. Therefore, in the case of changing the email address in IdP, you are required to change the registered email address in ProtoPie to the same address in IdP.

  Please refer to the procedure below when a service admin changes the email addresses of all members.

  1. Change all email addresses in IdP except the service admin account.
  2. Change all email addresses at Admin Dashboard in ProtoPie by the service admin.
  3. Service admin can change his/her own account by going to Account Setting → Profile.
  4. Complete the email address change by accessing an email service of your email address to be changed and check a confirmation email.

  Notice: If a verification method of the service admin is set to the SSO log-in, follow this procedure and change the IdP email address.

• I signed up by using the SSO. Can I log in by using Email/Password?

  If the Email/Password verification method is not enabled, you cannot use this method for the log-in. Once you enable Email/Password at Authentication in Service Admin Settings, you may log in.

  After this procedure, members can set their own passwords in Account Settings.

• I signed up to ProtoPie, but my first and last names are different from those in IdP.

  If you sign up by using SAML or OIDC, the first and last name are automatically loaded to IdP.

  • If the SAML value is not displayed correctly, please check the SAML Setting in IdP.
  • For OIDC, if the value is not displayed correctly, please check IdP.

• Does ProtoPie Enterprise support Single Logout (SLO)?

  Currently, ProtoPie Enterprise does not support Single Logout (SLO).

• What is the Entity ID value?

  An Entity ID is a globally unique name for a SAML entity, i.e., your Identity Provider (IdP) or Service Provider (SP). Entity ID is the name. It doesn’t have to be a resolvable web location. The SAML Entity ID must be a URI.

  ProtoPie Enterprise follows the format (ACS URL)

  • Enterprise Cloud: https://sample.protopie.cloud/api/auth/callback/sso/saml
  • Enterprise On-Premise: {PROTOPIE_HOST}/api/auth/callback/sso/saml

• Where can I get Cert data?

  ProtoPie (SP) does not currently provide cert data (X.509 cert).

  Our service reads the metadata provided by the IdP and uses the X.509 certificate if it exists in the metadata. If it does not exist, the X.509 certificate of the signature is obtained from the SAML response received as the ACS URL.

• Where can I get the ACS URL?

  The ACS URL provided by ProtoPie (SP) can be checked on the Admin Dashboard as follows: “Assertion Consumer URL”.

• What is the AuthnContext(same as AuthnContextClassRef)?

  In a SAML request, it is a means for a SP to ask the IDP to authenticate the user with a specific authentication mechanism. This is optional and depends on your IdP's setup options and requires confirmation from your IdP administrator.

  • urn:oasis:names:tc:SAML:2.0:ac:classes:X509
  • urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified