Integrating Identity Providers (IdP) in SGS

• Setting up the identity providers
• Examples
  • Cognito
  • Microsoft
    • Personal 
    • 365
  • Google
  • Facebook
  • Okta
  • IdentityServer4
• Managing the user lists
  • Integration of enterprise IdPs with SGS
  • Integration of social IdPs (e.g., Facebook, Google) with SGS

1. Configuration of the loginAuthSettings.json file to specify the IdPs SGS should recognize and interface with. Each of these properties must be accurately configured to ensure successful integration and communication between SGS and the selected IdPs.
2. Management of the lists of users authorized to access SGS. This involves the following:
   • Developing or implementing checker applications that act as intermediaries, handling the authentication data from the IdPs and determining whether a user logging in already has an SGS account. Existing users are logged in automatically, while new users trigger the application to apply the organization's policies, which may include account creation, permission assignments, or access denial.
   • (Optional) For bulk addition of user accounts to SkylineGlobe Server (SGS), organizations can use a custom script that retrieves a list of users, along with details such as names, email addresses, and role and then uses the SGS API to create user accounts in SGS in bulk, setting user properties and permissions accordingly.

Setting up the identity providers:

1. Locate the loginAuthSettings.json file in the SharedConfigurations folder under the Server Configuration Database Folder (whose location was defined during SGS installation), e.g., C:\SkylineGlobeServerConfiguration\SharedConfigurations\. This file includes a property named IdentityProviders, which is an array composed of objects. Each object represents an identity provider.
2. Add each identity provider you want to use as an object within the IdentityProviders array. For every provider object, include the properties: name, loginIcon, loginUrl, authTokenURL, authTokenURLRequestBody, and getUserInfoURL. The forceIdentityProvider property can be used to enforce a specific identity provider by setting its value to the name of one of the providers listed in the IdentityProviders array. Leave it as an empty string ("") if you don't want to enforce a specific provider. Here's a simplified example for configuring two providers. For a detailed example JSON illustrating the setup for various identity providers, see the attachment to this article.

   {
   "IdentityProviders": [
   {
   "name": "IDProvider1",
   "loginIcon": "iconURL1",
   "loginUrl": "loginURL1",
   "authTokenURL": "authTokenURL1",
   "authTokenURLRequestBody": "body1",
   "getUserInfoURL": "userInfoURL1"
   },
   {
   "name": "IDProvider2",
   "loginIcon": "iconURL2",
   "loginUrl": "loginURL2",
   "authTokenURL": "authTokenURL2",
   "authTokenURLRequestBody": "body2",
   "getUserInfoURL": "userInfoURL2"
   }
   ],
   "forceIdentityProvider": ""
   }

3. When configuring each IdP, it's helpful to distinguish between property attributes that are unique for each user and those that are common across all users of that IdP. Note that client_id and client_secret are user-specific values that need to be individually configured for each user setup.

   Properties:
   All IdP's have the same six properties. The precise attributes in each property as well as the attribute values may vary from one IdP to another.
   

   Property	Attribute	Type	Description
   name			Name of the Identity Provider as will be displayed in the login dialog.
   loginIcon			URL to an icon for the IdP's login button.
   loginUrl	base URL	Common/User-Specific	Base URL for the IdP's login endpoint.
   	redirect_uri	User-Specific	URL to which the IdP server redirects users after authentication. Depending on the configuration, this URL could redirect to SGS or another server application (e.g., checker for social IdPs).
   	response_type	Common	Set to =code for all IdP's that include this attribute.
   	client_id	User-Specific	Public identifier for your identity server.
   	scope	Common
   authTokenURL		Common/User-Specific	URL endpoint provided by the IdP where your server can request access tokens to authenticate and authorize users for your server.
   authTokenURLRequestBody	client_id	User-Specific	Public identifier for your server.
   	client_secret	User-Specific	Secret identifier for your identity server
   	grant_type	Common	Set to =authorization_code for all IdPs.
   getUserInfoURL	base URL	Common/User-Specific	URL for retrieving the user profile information (e.g., user’s name, email). This information is obtained from the IdP.
   	personFields	Common	Defines which fields of the user's profile information should be retrieved.
   	fields	Common	Defines which fields of the user's profile information should be retrieved.

    

     4.  After creating/modifying the configuration file, restart SGS for updates to take effect.

Examples

Detailed examples for IdPs like Cognito, Microsoft, Google, and Facebook are provided below. For a detailed example JSON illustrating the setup for all these identity providers, see the attachment to this article.

• Cognito
• Microsoft
• Google
• Facebook
• Okta
• IdentityServer4

Cognito

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Base URL: Obtained from your IdP application + /login? (See screenshot below)
  • redirect_uri: URL to which the IdP server should redirect users after authentication. 
  • response_type: Set to =code
  • client_id: Obtained from your IdP application (See screenshot below) 
    
• "authTokenURL": Obtained from your IdP application + /oauth2/token (See screenshot below)
• "authTokenURLRequestBody": 
  • client_id: Obtained  from your IdP application (See screenshot below)
  • client_secret: Obtained from your IdP application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Obtained from your IdP application + /oauth2/userInfo (See screenshot below)

{
"name": "Cognito",
"loginIcon": "https://mysite/logos/cognito256x219.png",
"loginUrl": "https://test.auth.us-east-1.amazoncognito.com/login?redirect_uri=https://mysite.com/sg/oauth/redirect&response_type=code&client_id=6d7qubrlgjdhersksm8ol1pc2c",
"authTokenURL": "https://test.auth.us-east-1.amazoncognito.com/oauth2/token",
"authTokenURLRequestBody": "client_id=6d7qubrlgjdhersksm8ol1pc2c&client_secret=1mtm9ftuukbm8oqp2oc9l73oaai92hulnl4kvib9nisrl91c8u81&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://test.auth.us-east-1.amazoncognito.com/oauth2/userInfo"
}

Microsoft

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Set to "https://login.live.com/oauth20_authorize.srf?" 
  • client_id: Obtained from your IdP application (See screenshot below) 
    
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
  • scope: Set to =wl.emails
  • response_type: Set to =code
• "authTokenURL": Set to "https://login.live.com/oauth20_token.srf" 
• "authTokenURLRequestBody": 
  • client_id: Obtained from your IdP application (See screenshot below)
  • client_secret: Obtained from your IdP application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Set to "https://apis.live.net/v5.0/me"

Personal

{
"name": "Microsoft",
"loginIcon": "https://mysite/logos/Microsoft256x219.png",
"loginUrl": "https://login.live.com/oauth20_authorize.srf?client_id=aa404e51-8760-4441-b0fe-424cb7559fea&redirect_uri=https://mysite/sg/oauth/redirect&scope=wl.emails&response_type=code",
"authTokenURL": "https://login.live.com/oauth20_token.srf",
"authTokenURLRequestBody": "client_id=aa404e51-8760-4441-b0fe-424cb7559fea&client_secret=iQL8Q~vtqAhznD3VvPe9~Y3xCht1pNAEOD8Yda-~&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://apis.live.net/v5.0/me"
}

365

{
"name": "Microsoft",
"loginIcon": "https://site.skyline.com/sg/images/MS.256x256.png",
"loginUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=5d1a0c8d-03ee-a116-a77D-d4a701f34e21&redirect_uri=https://skyline.com/sg/oauth/redirect&scope=openid+profile+email&response_type=code",
"authTokenURL": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"authTokenURLRequestBody": "client_id=5d1a0c8d-03ee-a116-a77D-d4a701f34e21&client_secret=ABCDE~wKEHkPnYMWH36~2gETxiEH7H-VatjJLbxY&grant_type=authorization_code&redirect_uri=https://skyline.com/sg/oauth/redirect",
"getUserInfoURL": "https://graph.microsoft.com/oidc/userinfo"
}

Google

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Set to "https://accounts.google.com/o/oauth2/v2/auth?" 
  • client_id: Obtained from your IdP application (See screenshot below) 
    
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
  • scope: Set to =openid email profile
  • response_type: Set to =code
• "authTokenURL": Set to "https://oauth2.googleapis.com/token" 
• "authTokenURLRequestBody": 
  • client_id: Obtained from your IdP application (See screenshot below)
  • client_secret: Obtained from your IdP application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Set to "https://people.googleapis.com/v1/people/me?"
  • personFields: Set to =names,emailAddresses

{
"name": "Google",
"loginIcon": "https://mysite/logos/google.256x256.png",
"loginUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=585398732296-6c6h8kl1s4er1vl7bkgqd0bhlp944of7.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fmysite%2Fsg%2Foauth%2Fredirect&scope=openid%20email%20profile&response_type=code",
"authTokenURL": "https://oauth2.googleapis.com/token",
"authTokenURLRequestBody": "client_id=585398732296-6c6h8kl1s4er1vl7bkgqd0bhlp944of7.apps.googleusercontent.com&client_secret=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&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://people.googleapis.com/v1/people/me?personFields=names,emailAddresses"
}

Facebook

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Set to "https://www.facebook.com/v14.0/dialog/oauth?" 
  • client_id: Obtained from your IdP application (See screenshot below)
  • redirect_uri: URL to which the IdP server should redirect users after authentication. 
    
  • scope: Set to =email
• "authTokenURL": Set to "https://graph.facebook.com/v14.0/oauth/access_token" 
• "authTokenURLRequestBody": 
  • client_id: Obtained from your IdP application (See screenshot below)
  • client_secret: Obtained from your IdP application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Set to "https://graph.facebook.com/v14.0/me?"
  • fields: Set to =email

{
"name": "Facebook",
"loginIcon": "https://mysite/logos/facebook.256x256.png",
"loginUrl": "https://www.facebook.com/v14.0/dialog/oauth?client_id=616496163768891&redirect_uri=https://mysite/sg/oauth/redirect&scope=email",
"authTokenURL": "https://graph.facebook.com/v14.0/oauth/access_token",
"authTokenURLRequestBody": "client_id=616496163768891&client_secret=9ee6cc364bdad30ed4a0d75487c21465&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://graph.facebook.com/v14.0/me?fields=email"
}

Okta

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Base URL: Obtained from your IdP application + /oauth2/v1/authorize? (See screenshot below)
  • response_type: Set to =code
  • redirect_uri: URL to which the IdP server should redirect users after authentication. 
  • client_id: Obtained from your IdP application (See screenshot below) 
    
• "authTokenURL": Obtained from your IdP application + /oauth2/v1/token (See screenshot below)
• "authTokenURLRequestBody": 
  • client_id: Obtained  from your IdP application (See screenshot below)
  • client_secret: Obtained from your IdP application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Obtained from your IdP application + /oauth2/v1/userinfo (See screenshot below)

{
"name": "Okta",
"loginIcon": "https://mysite/logos/images/okta.256x256.png",
"loginUrl": "https://trial-3036531.okta.com/oauth2/v1/authorize?response_type=code&client_id=0oa5m587i2b0j2T7X697&redirect_uri=https://mysite/sg/oauth/redirect&scope=openid%20email%20profile",
"authTokenURL": "https://trial-3036531.okta.com/oauth2/v1/token",
"authTokenURLRequestBody": "client_id=0oa5m587i2b0j2T7X697&client_secret=81YfiITWv6nxXXOn9Jf2QOza2Pzq0DSnnh7NMJna&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://trial-3036531.okta.com/oauth2/v1/userinfo"
}

IdentityServer4

IdentityServer4 is an OpenID Connect and OAuth 2.0 framework specifically designed for ASP.NET Core applications. It provides centralized authentication logic, single sign-on capabilities, access control for APIs, and support for external identity providers like Azure Active Directory and Google.

Properties/Attributes:

• "name": String with name of IdP
• "loginIcon": URL to your IdP logo
• "loginUrl": Your server URL + /authorize/
  • client_id: As was set in your IdentityServer4 application (See screenshot below) 
  • redirect_uri: URL to which the IdP server should redirect users after authentication. 
  • scope: Set to =openid%20email%20profile
  • response_type: Set to =code
• "authTokenURL": Your server URL + /token
• "authTokenURLRequestBody": 
  • client_id: As was set in your IdentityServer4 application (See screenshot below)
  • client_secret: As was set in your IdentityServer4 application (See screenshot below)
  • grant_type: Set to =authorization_code
  • redirect_uri: URL to which the IdP server should redirect users after authentication.
• "getUserInfoURL": Your server URL + /userinfo

{
"name": "IdentityServer4",
"loginIcon": "https://mysite/logos/ids4.png",
"loginUrl": "https://myserver/myApplication/authorize?client_id=MyClientID&redirect_uri=https://mysite/sg/oauth/redirect&scope=openid%20email%20profile&response_type=code",
"authTokenURL": "https://myserver/myApplication/token",
"authTokenURLRequestBody": "client_id=MyClientID&client_secret=MyClientSecret&grant_type=authorization_code&redirect_uri=https://mysite/sg/oauth/redirect",
"getUserInfoURL": "https://myserver/myApplication/userinfo"
}

Managing the user lists

In the management of user lists within SkylineGlobe Server (SGS) for both social and enterprise Identity Providers (IdPs), the procedure involves an initial step using a checker application that interfaces between the IdP and SGS. This application handles the authentication data from the IdP and uses the the SGS API. to determine if a user attempting to log in via an IdP already has an SGS account. Existing users are logged in automatically, while new users trigger the application to apply the organization's policies, which may include account creation, permission assignments, or access denial.

Bulk User Addition (Optional)

To add user accounts in bulk to SkylineGlobe Server (SGS), organizations can use a custom script. This script retrieves a list of users, along with details such as names, email addresses, and roles. See the sample script (AddUser.html) attached to this article.

For enterprise Identity Providers (IdPs), the script pulls user data directly from the IdP's system. With social IdPs, it may need to gather user data from alternate organizational records or databases maintained by the organization. After collecting the user data, the script uses the SGS API to create user accounts in SGS in bulk, setting user properties and permissions accordingly. This process should be repeated periodically to ensure the user database in SGS remains current, reflecting any organizational changes like new hires or departures.

<html>
    <head></head>
    <body onload = "init()">
        <script language= "JavaScript">
        var server = "https://yourSite/sg/";
        var userName = "abcdef@gmail.com"; // should be retrieved from the customized login form
        var Password = "newPassword";
        var siteName = "default";
        var Role = "Publisher";
        var param = "" // to be retrieved from IdP reply. See example from Google:
        //"state=eyJyZWZlcnJlciI6ImZ1c2lvbiIsImN1cnJlbkkjh57ddslvbiI6Imh0dHBzOi8vZGV2LnNreWxpbmVzb2Z0LmNvbS9zZy9BZG1pbi90ZWxvZ2luLmFzcHg%2FZnVzaW9uUmVkaXJlY3RVUkw9aHR0cHMlM0ElMkYlMkZkZXYuc2t5bGluZXNvZnQuY29tJTJGc2clMkZ0ZWYlMkZ0ZS5odG1sJTNGIiwic2l0ZSI6IkRlZmF1bHQiLCJsb2dpblVybCI6Imh0dHBzOi8vZGV2LnNreWxpbmVzb2Z0LmNvbS9zZy9EZWZhdWx0IiwiZnVzaW9uUmVkaXJjgnfjd849sdnhjiJodHRwczovL2Rldi5za3lsaW5lc29mdC5jb20vc2cvdGVmL3RlLmh0bWw%2FIiwic2dTU09LZXkiOiJHb29nbGUiLCJmdXNpb25Gcm9tU1NPIjp0cnVlLCJyZW1lbWJlck1lIjp0cnVlfQ%3D%3D&code=4%2F0AeaAABAO-KvwlYzemrQHCaIvTRp1qvE79Fnx0ilChjjq80Jt96wi31380D9asiXa487XVQ&scope=email+profile+openid+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile&authuser=0&prompt=none";
            function init(){             
                // connect with admin credentials to implement SGS API as Super Admin \ Site Admin: check if user exist and create user \ deny access
                fetch(server + siteName + "/ConnectSG", {
                    "body": "{\n  \"request\": \"login\",\n  \"username\": \"someone\",\n  \"password\": \"someone'sPassword\"\n , \"isPersistent\": true\n}",
                    "method": "POST",}).then((response) => response.json()).then((response) =>{if(response.result == "success") checkUser(userName);});  
            }          
            function checkUser(userName){               
                //check if user exist and implement policy: addUser > login OR login OR deny access
                // in this example, the code checks if the user exist: exist? log them in OR does not exist? create one and then log them in.
                fetch(server + siteName + "/api/v1/user/get?userName=" + userName ,{}).then((response) => response.json()).then((response) =>{ if(response.result == "failed") { alert(response.result); addUser(userName, Password, siteName);} else { login(param);}});              
            }
            function addUser(userName, Password, siteName){               
                // in case policy wants to add user, use the user/create API to add them.
                fetch(server + siteName + "/api/v1/user/create?userName=" + userName + "&permissionType=" + Role + "&txtNewPW=" + Password, {
                }).then((response) => response.json()).then((response) => {if(response.result == "success") {login(param)} else {alert("could not add"); }});
            }
            function login(param){               
                //redirect to origin (TEF\SG\TED) with the known credentials. The location is set automatically. So, if the user attempted to log in from TEF, they will be redirected to the same application.
                window.location = server + "oauth/redirect?" + param;
                }
        </script>
    </body>
</html>