OAuth 2.0 provider

To create an OAuth 2.0 Identity Provider, you must access the Identity provider list on the Safewhere Admin portal and choose to create one of the supported social media providers:

swadmin-social-provider-creation

Google

Google application setup

It is possible to authenticate users into a federation using their Google account. Before it even becomes relevant to set up the Google provider connection, you must register Safewhere Identify as an Application with Google. The link to do this is:

https://console.cloud.google.com/iam-admin/projects

After signing up as a Google developer, you can start registering Safewhere Identify as an application as follows:

  1. Register your Safewhere Identify installation using the "Create project" button, input a project name and click "Create"

google-app-registration

  1. Wait until the project is created successfully. On the dashboard of the newly created project, access the APIs & Services\Credentials menu.

google-app-credential

Once the "Credentials" form opens, choose "Create credentials" and select "OAuth client ID"

google-app-credential-oauthclientid

You may be asked to specify the product name. Next, you need to choose the "Configure consent screen" setting:

google-app-consent

Select the appropriate option for your setup:

google-app-consent-page

  1. Back to the "Credentials" form, choose "Create credentials" and select "OAuth client ID". On this form you will input the following values that points to your Safewhere Identify installation:

    • Application type: Select "Web application"
    • Name: Input the name of the credential.
    • Authorized Javascript origins: Input the Identify site URL without a trailing slash "/", for example https://identifydomain (Note: You need to add the domain of your Identify instance to the Authorised domains list of the OAuth consent screen)
    • Authorized redirect URI: Input the URI using the following format:

Make sure there are no whitespaces at the start and end.

google-app-credential-oauthclientid-form

Once registered, you will be given a number of important information that you will use to set up the Google connection in Safewhere Identify. These are:

  • Client ID: The unique number that your app is given with Google.
  • Client Secret: A secret code that will be used to ensure that your installation of Safewhere Identify is the only one that can use the Google authentication app setup.

google-app-credential-oauthclientid-info

Note: You must enable the Google+ API and Google People API on the Google Cloud platform

google-app-google-api

google-app-google-people-api

In addition, some Google attributes may need user approval before they are sent to the Identify:

google-user-permission

Google identity provider setup

Now that you have Safewhere Identify registered with Google, you can continue to create a new Google authentication in Safewhere Admin.

  1. After saving the new connection, access its connection tab and update the settings:

    • Client id (App id): The App Id automatically generated by Google.
    • Client secret: The secret code automatically generated by Google.

swadmin-google-connection

  1. You can also access the Permission tab to grant additional permissions:

swadmin-google-permission

  • Required permissions: There are default values: openid, profile (It collects the Google attributes: "id", "displayName", "name", "url", "gender", "givenName", "middleName", "familyName"), email
  • Additional permissions: You can add "plus.login"(a.k.a https://www.googleapis.com/auth/plus.login) for collecting the age_range

Here is the mapping list from Google attributes to Identify claims:

Google attribute Identify claim
id  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier 
displayName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
email  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 
givenName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname 
middleName  urn:identify:middlename 
familyName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname 
url  urn:google:profile 
gender  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender 
birthday  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth 
age_range (min)  urn:google:age_range_min 
age_range (max)  urn:google:age_range_max 

Note: All attributes that are not listed in the table above are mapped to the urn:google:[attributename] claim.

  1. Besides the actual Google specific configuration settings, there are a whole range of fields that will help you set up a two factor authentication process. Below, each of these are explained in turn.

    • Second factor authentication connection: If you want this Facebook Authentication Connection to have a second factor, you must choose this second factor among the different Authentication Connections that have been set up in the system. This includes all the One Time Password Connections.
    • Two factor identities condition: When using two different Authentication Connections together (which is basically what you are doing when setting up two-factor authentication, then the two may try to Safewhere Identify the incoming user based on two different identity bearing claims. This dropdown is activated when a user has chosen, that the connection will have a second factor. Options in the dropdown are:
      • Use the first identity: System will disregard the "Identity bearing claim" value of the second factor and just focus on identifying the user based on the first one.
      • Two identities must be the same: The user will not be allowed to log in unless the identity of the user for the first factor is identical to that of the second factor.

swadmin-google-2factor

To see how the authentication page looks to the users, please click here.

Facebook

Facebook application setup

It is possible to authenticate users into a federation using their Facebook account. Before it even becomes relevant to set up the Facebook authentication connection in Safewhere Identify, you must register Safewhere Identify as an Application with Facebook. The link to do this is:

https://developers.facebook.com/apps/

After signing up as a Facebook developer, you can start registering Safewhere Identify as an application as follows:

  1. Register your Safewhere Identify installation using the "Create App" button.

facebook-app-registration

This will start a wizard of New App ID, where you can insert information about its display name and contact email.

facebook-app-appid

  1. Select Settings\Basic, you see this form and customize the following information:
  • Display name: A name identifying the application (could e.g. be the Safewhere Identify site name).
  • Namespace: Not relevant.
  • Contact email: Primary email used for important communication related to the app.
  • App Domains: Input the Identify domain.
  • Privacy Policy URL: Input your policy URL
  • Terms of Service URL: Input your terms of service URL (You need to input a valid URL as Facebook validates and detects this URL)

facebook-app-basic-setting

At the end of this form, select "Add platfom" and choose "Website"

facebook-app-platform

Input the below URL to the Site URL field:

  1. You need to add Identify URI to Valid OAuth redirect URIs list in the app's Login Settings. This rule was applied since Mar 2018 (refer to here)

facebook-app-login

Note: When you first register your app, it will be set to development mode

facebook-app-mode

  1. You need to carry out the following steps in order to switch it to live mode:

After your app is "live", you need to update the Site URL from "https://identifydomain/runtime/" to "https://identifydomain/runtime/facebook/consume.idp" and save your app again.

Facebook identity provider setup

Now that you have Safewhere Identify registered with Facebook, you can continue to create a new Facebook authentication in Safewhere Admin.

  1. After saving the new connection, access the connection tab and update the settings:
  • Client id (App id): The App Id automatically generated by Facebook.
  • Client secret: The secret code automatically generated by Facebook.

swadmin-facebook-connection

  1. You can also access the Permission tab to grant additional permissions.

swadmin-facebook-permission

  • Additional attributes: You can add "cover", "middle_name", "age_range", "link", "locale", "picture", "timezone", "updated_time", "verified", "gender", "birthday", "website", "hometown", "location", "work", "education", "about". When a attribute is selected on additional attributes input, its corresponding permission will be selected on additional permissions input.
  • Required permissions: There are default values: "public_profile", "email"
  • Additional permissions: You can add user_birthday (birthday), user_website (website), user_hometown (hometown), user_location (location), user_work_history (work), user_education_history ("education"), user_about_me (about)

Here is the overview of how Facebook attributes are mapped to Identify claims:

Facebook attribute identify claim
id  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier 
age_range (min)  urn:facebook:age_range_min 
age_range (max)  urn:facebook:age_range_max 
birthday  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth 
email  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 
name  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
first_name  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname 
middle_name  urn:identify:middlename 
last_name  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname 
gender  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender 
link  urn:facebook:link 
location  urn:facebook:location 
locale  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality 
timezone  urn:facebook:timezone 

Note: All attributes that are not listed in the table above are mapped to the urn:facebook:[attributename] claim.

  1. Besides the actual Facebook specific configuration settings, there are a whole range of fields that will help you set up a two factor authentication process. Below, each of these are explained.
  • Second factor authentication connection: If you want this Facebook Authentication Connection to have a second factor, you must choose this second factor among the different Authentication Connections that have been set up in the system. This includes all the One Time Password Connections.
  • Two factor identities condition: When using two different Authentication Connections together (which is basically what you are doing when setting up two-factor authentication, then the two may try to Safewhere Identify the incoming user based on two different identity bearing claims. This dropdown is activated when a user has chosen, that the connection will have a second factor. Options in the dropdown are:
    • Use the first identity: System will disregard the "Identity bearing claim" value of the second factor and just focus on identifying the user based on the first one.
    • Two identities must be the same: The user will not be allowed to log in unless the identity of the user for the first factor is identical to that of the second factor.

swadmin-facebook-2factor

To see how the authentication page looks to the users, please click here.

Twitter

Twitter application setup

It is possible to authenticate users into a federation using their Twitter account. Before it even becomes relevant to set up the Twitter authentication connection in Safewhere Identify, you must register Safewhere Identify as an Application with Twitter. The link to do this is:

https://dev.twitter.com/apps

After signing up as a Twitter account, you can start registering Safewhere Identify as an application:

  1. Register your Safewhere Identify installation using the "Create an app" button.

twitter-app-registration

You are required to have a "Twitter developer account" before starting to create any new app.

twitter-app-requirement

  1. After you have a "Twitter developer account" and have created a new app, you must fill in all required information. You must input the below URL to the setting Callback URLs

twitter-app-detail

  1. You can collect the info about API key and its secret key on the "Keys and tokens" tab.

twitter-app-key-token

Twitter has a strict policy in terms of what you can pull from them. You can ask for a basic user profile, but email address will need elevated permission: verify_credentials and email. To get the email from Twitter, you need to access "Permissions" tab on the selected application, enable "Request email addresses from users" field at the "Additional Permissions" section and click on Save button

twitter-app-permission

Twitter identity provider setup

Now that you have Safewhere Identify registered with Twitter, you can continue to create a new Twitter authentication in Safewhere Admin.

  1. After saving the new connection, access its connection tab and update the settings:
  • Client id (App id): The App Id automatically generated by Twitter.
  • Client secret: The secret code automatically generated by Twitter.

swadmin-twitter-connection

  1. There is no required permission as well as the additional permission, the settings at its Permissions tab is read-only

swadmin-twitter-permission

  • Required permissions: you only have "basic_profile"

Here is the mapping list from the Twitter attributes to the Identify claims:

Twitter attribute identify claim
UserId  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier 
UserId  urn:twitter:userid 
ScreenName  urn:twitter:screenname 
ScreenName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
email  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 

Note: All attributes that aren’t listed in the table above are mapped to urn:twitter:[attributename] claim.

  1. Besides the actual Twitter specific configuration settings, there are a whole range of fields that will help you set up a two factor authentication process. Below each of these are explained.
  • Second factor authentication connection: If you want this Twitter Authentication Connection to have a second factor, you must choose this second factor among the different Authentication Connections that have been set up in the system. This includes all the One Time Password Connections.
  • Two factor identities condition: When using two different Authentication Connections together (which is basically what you are doing when setting up two-factor authentication, then the two may try to Safewhere Identify the incoming user based on two different identity bearing claims. This dropdown is activated when a user has chosen, that the connection will have a second factor. Options in the dropdown are:
    • Use the first identity: System will disregard the "Identity bearing claim" value of the second factor and just focus on identifying the user based on the first one.
    • Two identities must be the same: The user will not be allowed to log in unless the identity of the user for the first factor is identical to that of the second factor.

To see how the authentication page looks to the users, please click here.

LinkedIn

LinkedIn application setup

It is possible to authenticate users into a federation using their LinkedIn account. Before it even becomes relevant to set up the LinkedIn authentication connection in Safewhere Identify, you register Safewhere Identify as an Application with LinkedIn. The link to do this is:

https://www.linkedin.com/secure/developer

After signing up as a LinkedIn developer, you can start registering Safewhere Identify as an application as follows:

  1. Register your Safewhere Identify installation using the "Create app" button.

linkedin-app-registration

This will open a form where you can add info about the app as here shown

linkedin-app-form

  1. Once registered you will be given a number of important information to set up the Linked connection in Safewhere Identify.
  • At its Setting tab, you add your Identify domain on Additional settings

linkedin-app-setting

  • At its Auth tab, you have:

    • Client ID: The unique number that your app is given with LinkedIn.
    • Client Secret: A secret code that will be used to ensure that your installation of Safewhere Identify is the only one that can use the Facebook authentication app setup.
    • Redirect URLs: Insert the URLs using the following format:

linkedin-app-auth

  • At its Products tab, you add the "Sign In with LinkedIn" product

linkedin-app-products

  • After the product is approved, you have two more permissions at its Auth tab

linkedin-app-auth-permission

LinkedIn identity provider setup

Now that you have Safewhere Identify registered with LinkedIn, you can continue to create a new LinkedIn authentication in Safewhere Admin.

  1. After saving the new connection, access its connection tab and update the settings:
  • Client id (App id): The App Id automatically generated by LinkedIn.
  • Client secret: The secret code automatically generated by LinkedIn.

swadmin-linkedin-connection

  1. You can also access its Permission tab to grant more additional permissions

swadmin-linkedin-permission

  • Additional attributes: You can add "headline", "birthDate", "address", "associations", "certifications", "contactInstructions", "educations",
    ims", "languages", "maritalStatus", "organizations", "phoneNumbers", "skills", "supportedLocales", "websites", "testScores", "projects",
    volunteeringExperiences", "honors", "courses". When a attribute is selected on additional attributes input, its corresponding permission will be selected on additional permissions input.
  • Required permissions: There are default values: "r_liteprofile", "r_emailaddress"
  • Additional permissions: You can add "r_basicprofile", "r_fullprofile"

Here is the mapping list from the LinkedIn attributes to the Identify claims:

LinkedIn attribute identify claim
Id  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier 
vanityName (if vanityName value doens't return, it uses emailAddress value)  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
emailAddress  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 
localizedFirstName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname 
localizedLastName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname 
birthDate http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth 

Note: All attributes that aren’t listed in the table above are mapped to urn:linkedin:[attributename] claim.

  1. Besides the actual LinkedIn specific configuration settings, there are a whole range of fields that will help you set up a two factor authentication process. Below each of these are explained.
  • Second factor authentication connection: If you want this Linkedln Authentication Connection to have a second factor, you must choose this second factor among the different Authentication Connections that have been set up in the system. This includes all the One Time Password Connections.
  • Two factor identities condition: When using two different Authentication Connections together (which is basically what you are doing when setting up two-factor authentication, then the two may try to Safewhere Identify the incoming user based on two different identity bearing claims. This dropdown is activated when a user has chosen, that the connection will have a second factor. Options in the dropdown are:
    • Use the first identity: System will disregard the "Identity bearing claim" value of the second factor and just focus on identifying the user based on the first one.
    • Two identities must be the same: The user will not be allowed to log in unless the identity of the user for the first factor is identical to that of the second factor.

swadmin-linkedin-2factor

To see how the authentication page looks to the users, please click here.

Microsoft Live

Microsoft Live application setup

It is possible to authenticate users into a federation using their Microsoft account. Before it even becomes relevant to set up the Microsoft Live authentication connection in Safewhere Identify, we must register Safewhere Identify as an Application. The link to do this is:

https://portal.azure.com/

After signing up as a Microsoft account, you can start registering Safewhere Identify as an application:

  1. Choose "App registrations"...

microsoft-app-registration

...and register your Safewhere Identify installation using the "New registration" button at "App registrations".

microsoft-app-new-registration

  1. When the new application form displays, you input the following information,,,
  • Name: A name identifying the application (could e.g. be the Safewhere Identify site name).
  • Supported account types: Specifies who can use this application or access this API
  • Redirect URI: Selects "Web"option and insert the URLs using the following format:

,,,and click "Register".

microsoft-app-new-form

  1. Choose "Authentication" on the left panel of the app you just created and input the Logout URL using the following format...

... and click Save.

microsoft-app-authentication

  1. Choose "Certificates & secrets" on the left panel of the app you created and generate a new client secret.

microsoft-app-clientsecret

Microsoft Live identity provider setup

Now that you have Safewhere Identify registered with Microsoft, you can continue to create a new Microsoft Live authentication in Safewhere Admin.

  1. After saving the new connection, access its connection tab and update the settings:
  • Client id (App id): The App Id automatically generated by Microsoft. You can find its info at Overview setting of your Microsoft app.

microsoft-app-appid

  • Client secret: The secret code automatically generated by Microsoft.

swadmin-microsoft-connection

  1. There are no additional permissions to set. The settings on the Permissions tab are read-only

swadmin-microsoft-permission

  • Required permissions: You only have "Basic profile"

Here is the mapping list from the Microsoft attributes to the Identify claims:

Microsoft attribute identify claim
id  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier 
displayName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 
mail  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 
userPrincipalName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn  
mobilePhone  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone 
givenName  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname 
surname  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname 
birthday  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth 
country  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country 

Note: All attributes that aren’t listed in the table above are mapped to urn:microsoft:[attributename] claim.

  1. Besides the actual Microsoft specific configuration settings, there are a whole range of fields that will help you set up a two factor authentication processd. Below each of these are explained.
  • Second factor authentication connection: If you want this Microsoft Authentication Connection to have a second factor, you must choose this second factor among the different Authentication Connections that have been set up in the system. This includes all the One Time Password Connections.
  • Two factor identities condition: When using two different Authentication Connections together (which is basically what you are doing when setting up two-factor authentication, then the two may try to Safewhere Identify the incoming user based on two different identity bearing claims. This dropdown is activated when a user has chosen, that the connection will have a second factor. Options in the dropdown are:
    • Use the first identity: System will disregard the "Identity bearing claim" value of the second factor and just focus on identifying the user based on the first one.
    • Two identities must be the same: The user will not be allowed to log in unless the identity of the user for the first factor is identical to that of the second factor.

swadmin-microsoft-2factor

To see how the authentication page looks to the users, please click here.