Learn what you need to know and prepare before you set up your SSO login provider.
Introduction
We support several SSO providers. Learn about the scope below.
Ready to set up SSO yourself? Go for it!
Supported SSO providers
- OAuth2.0/OIDC
An external login provider needs to support OAuth2 + OpenID to be used for external user authentication. We support the entire OICD scope. The supported OAuth providers are:
- SAML
- signed SAML IdP responses (default)
- encrypted SAML IdP responses (usually not used, but readily supported)
Configurations and scope per SSO provider
For Google sign-in, the customer needs to create a web app in the Google app console. The steps are:
- Go to the Google API Console
- Open the Credentials page.
- Click Create credentials > OAuth client ID.
- Select the Web application type.
- Name your OAuth 2.0 client application.
- Add the Authorized redirect URI (e.g. https://collaboard-app.customer.com/authenticate)
- Click Create
- Copy the Client ID and Client secret displayed
{
"Provider": "Google",
"ClientId": "<The Google client ID>",
"ClientSecret": "<The Google client secret>",
"RedirectUri": "https://collaboard-app.customer.com/authenticate",
"AuthorizeUri": "https://accounts.google.com/o/oauth2/v2/auth",
"TokenUri": "https://www.googleapis.com/oauth2/v4/token",
"Scope": "openid email profile"
}
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).
Microsoft
For Microsoft sign-in, the customer first needs to create a web app in Microsoft active directory. The steps are:
- Go to the Azure portal
- Select Azure Active Directory.
- Select App Registrations and click on New Registration.
Collaboard Single Sign On - Name your OAuth 2.0 client application.
- Select the appropriate accounts type.
- Add the Authorized redirect URI (e.g. https://collaboard-app.customer.com/authenticate)
- Click Create
- Copy the Application (client) ID
- Click "Certificates and secrets"
- Click "New client secret", select the expiration date and copy the Value displayed.
{
"Provider": "Microsoft",
"ClientId": "<The Microsoft client ID>",
"ClientSecret": "<The Microsoft client secret>",
"RedirectUri": "https://collaboard-app.customer.com/authenticate",
"AuthorizeUri": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
"TokenUri": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"Scope": "openid email profile"
}
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).
Apple
For Apple sign-in, the customer first needs to create an Apple app registration.
For instructions on how to do this, please see how to configure sign in with Apple.
The provider object shall have the following format:
{
"Provider": "Apple",
"ClientId": "<The Apple client ID>",
"ClientSecret": "<The Apple client secret>",
"RedirectUri": "https://collaboard-app.customer.com/server/auth/api/Authorization/HandleExternalLoginCallback?app=webapp&provider=Apple&redirectUri=https%3A%2F%2Fcollaboard-app.customer.com%2Fauthenticate",
"AuthorizeUri": "https://appleid.apple.com/auth/authorize",
"TokenUri": "https://appleid.apple.com/auth/token",
"Scope": "name email"
}
Because Apple is using POST to send back the response, the web api needs to handle the response before sending it back to the client, so the redirect URI will be in the form:
{Collaboard authentication API URI}/api/Authorization/HandleExternalLoginCallback?app=webapp&provider=Apple&redirectUri={URL-encoded value of the Collaboard web application root URI}%2Fauthenticate
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).
ADFS
Important: Self-signed certificates are not supported.
For ADFS, the provider object shall have the following format:
{
"Provider": "ADFS",
"ClientId": "<The ADFS application id for Collaboard>",
"ClientSecret": "<The ADFS secret key for the Collaboard app>",
"RedirectUri": "https://collaboard-app.customer.com/authenticate",
"AuthorizeUri": "<The ADFS authorize URI>",
"TokenUri": "<The ADFS token URI>",
"Scope": "openid email profile"
}
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).
Also, in the id_token returned by ADFS, the claims needed are:
| Claim | Description | Required |
| unique_name or preferred_username | The user name | Yes |
| The user's email | Yes | |
| given_name | The user's first name | No |
| family_name | The user's last name | No |
| name | The user's full name | No |
| picture | The user's profile photo url | No |
OAuth
OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 framework. It allows third-party applications to verify the identity of the end-user and to obtain basic user profile information. OIDC uses JSON web tokens (JWTs), which can be obtained using flows conforming to the OAuth 2.0 specifications. The basic (and required) scope for OIDC is openid, which indicates that an application intends to use the OIDC protocol to verify a user's identity. Beyond that, an application can also ask for additional scopes.
The claims that are included for the most commonly-used scopes are listed below:
| Scope | Claims |
| openid | Returns the sub claim, which uniquely identifies the user |
| Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user. |
|
| profile | Returns claims that represent basic profile information, including name, family_name, given_name, middle_name, nickname, picture, and updated_at. |
The required scopes are openid and email. The profile scope is recommended as well, as it will provide more information for the authenticated user.
Our service API is using this Authorization Code flow.
The external login service must provide at least an authorize endpoint and a token endpoint, to be used by the above flow.
The external login service must have a client configured with the provided redirect url, and provide the client id and client secret.
In the id_token returned by the service, the claims needed are:
| Claim | Description | Required |
| unique_name or preferred_username | The user name | Yes |
| The user's email | Yes | |
| given_name | The user's first name | No |
| family_name | The user's last name | No |
| name | The user's full name | No |
| picture | The user's profile photo url | No |
The information returned in these claims will be used to populate the user's profile in Collaboard with the respective data, such as email, first / last / full name and profile picture.
For OAuth, the provider object shall have the following format:
{
"Provider": "OAuth",
"ClientId": "<The OAuth application id for Collaboard>",
"ClientSecret": "<The OAuth secret key for the Collaboard app>",
"RedirectUri": "https://collaboard-app.customer.com/authenticate",
"AuthorizeUri": "<The OAuth authorize URI>",
"TokenUri": "<The OAuth token URI>",
"Scope": "openid email profile"
}
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).
SAML
To integrate with an identity provider using the SAML 2.0 protocol, we will need the XML Metadata of the provider. A sample IdP XML metadata file would look like this:
<EntityDescriptor entityID="urn:idp.example.org"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<KeyInfo
xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIDBzCCAe+gAwIBAgI...P3Z3TTTs=</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.org/saml/logout"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.org/saml/logout"/>
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.org/saml"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.org/saml"/>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="E-Mail Address"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Given Name"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Name"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Surname"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Name ID"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/>
</IDPSSODescriptor>
</EntityDescriptor>
Alternatively, we would need the following information from the identity provider:
- IdP EntityID
- IdP Redirect URL
- IdP Logout URL
- IdP public certificate
- NameId Format
User-specific attributes returned by the authentication response In the SAML Response message, the attributes needed are:
Username (any of the following can be used):- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
- NameID (in the SAML Response Subject element).
- User.email
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
The optional attributes are:
First Name (any of the following can be used):
- first_name
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- User.FirstName
- givenName
- last_name
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sm
- User.LastName
- sn
Profile picture (any of the following can be used):
- picture
Singed Responses
Our SAML Service Provider supports signed responses from the Identity Provider, to verify that the response hasn't been tampered with by an unauthorized third-party, via the ClientSecret parameter in the JSON configuration object.
Encrypted Responses
Our SP also supports encrypted SAML IdP responses via the ExtraProperties.DecryptionCertificate parameter in the JSON configuration object. The IdP would encrypt the response using the certificate provided by the SP (and also defined in the SP SAML configuration metadata) and the SP will use its the private key to decrypt the response. If this configuration parameter is omitted, the SP will not create signed requests.
Our SP can also create signed SAML requests, via the ExtraProperties.SigningCertificate parameter in the JSON configuration object. The SP would use its private key to sign a request, and the IdP would use the certificate provided by the SP (and also defined in the SP SAML configuration metadata) to verify the SP request signature. If this configuration parameter is omitted, the SP will not support encrypted IdP responses.
The provider JSON object will be:
{
"Name": "My SSO provider",
"Provider": "SAML",
"ClientId": "<The EntityID for the Collaboard application>",
"ClientSecret": "<The IdP public X509 certificate for verifying the SAML assertion signature>",
"AuthorizeUri": "<The IdP login URI>",
"RedirectUri": "https://collaboard-app.customer.com/server/auth/api/Authorization/HandleExternalLoginCallback?app=webapp&provider=SAML&redirectUri=https%3A%2F%2Fcollaboard-app.customer.com%2Fauthenticate",
"LogoutUri":: "<The IdP logout URI, if applicable>",
"LogoutRedirectUri": "https://collaboard-app.customer.com/server/auth/api/Authorization/HandleExternalLogoutCallback?app=webapp&provider=SAML&redirectUri=https%3A%2F%2Fcollaboard-app.customer.com%2Fauthenticate",
"TokenUri": null,
"Scope": null,
"ExtraProperties": {
"SigningCertificate": {
"Certificate": "<The SP public X509 certificate, used by the IdP for verifying signed SAML requests created by the SP>",
"PrivateKey": "<The private key for creating signed SAML requests>"
},
"DecryptionCertificate": {
"Certificate": "<The SP public X509 certificate, used by the IdP to create encrypted assertions>",
"PrivateKey": "<The private key used by the SP to decrypt IdP assertions, encrypted using the above SP certificate>"
}
}
}
In the SAML case, because the IdP is using POST to send back the response, the web API needs to handle the response before sending it back to the client, so the redirect URI will be in the form:
{Collaboard auth API URI}/api/Authorization/HandleExternalLoginCallback?app=webapp&provider=SAML&redirectUri={URL-encoded value of the Collaboard web application root URI}%2Fauthenticate
In the above example, you need to replace the RedirectUri collaboard-app.customer.com with the domain in which you are hosting the Collaboard web application (on premise installation)/ the Collaboard default SSO params found at SSO setup (Cloud customer).