Setting Up a Microsoft Account SSO for OAuth2

The administration platform allows you to use a Microsoft account for OAuth2 authentication. The corresponding procedure is detailed in this document.

Prerequisites

To set up OAuth2 with a Microsoft account, you need:

• The URL of your server (public or private).
  For example, "https://www.my_server.com" or "https://MyServerName".
• A Microsoft account to administer the service. This can be done from the this link.
  In the following example, we will use mock account "my_admin_account@live.com".
• To select a name for your OAuth2 service. It must start with a letter (A-Z or a-z), followed with any combination of letters (A-Z or a-z), digits, or underscores.
  In the following example, the name "Microsoft" is used.
• To configure Oauth2 as a valid authentication method in your Sage X3 nodelocal.js file:
  

  session: {timeout: 30, // minutescheckInterval: 60, // secondsauth: ["basic", "oauth2"]}

Creating a client ID

1. Go to https://apps.dev.microsoft.com and click Add an app.
   
2. Enter the name of the application you want to create and click Create application.
   
3. Click Generate a Password in the Application Secrets section.
   Copy the password to a safe place for future reference. You will need it again during the process.
   
4. Click Add a platform in the Platforms section, and select Web.
5. Enter the redirection Url: http(s)://X3host:X3port/auth/oauth2/Microsoft/loginCallbackwhere X3host is the host of your "Syracuse" Web server, and X3port is the port of your "Syracuse" Web server.
   There is no need to specify the port if you are using port 80 with http or port 443 with https as those are the default ports.
   
6. Save the application.

Creating an Oauth2 service in the Sage X3 Web Server (Update 9)

1. Go to Administration > Administration > Settings > Authentication > OAuth2 Servers.
2. Click New OAuth2 service.
3. In the Name field, enter the name of the service created in the Prerequisites section.
   The display name can be chosen freely.
4. Enter the appropriate values for the following fields:
   • Oauth2 server URL without path: "https://login.microsoftonline.com"
   • Path for authorization: "https://login.microsoftonline.com/common/oauth2/V2.0/authorize"
   • Path to get access token: "https://login.microsoftonline.com/common/oauth2/V2.0/token"
   • Oauth2 client ID and Oauth2 client secret correspond to the client ID and the password defined in the Creating a client ID section.
   • Scope for Oauth2 requests: "User.Read"
   • Redirect path for Oauth2 server depends on the Sage X3 Web server and on the service name selected in the Prerequisites section.
     If the field can be edited, enter the Web server address followed with "/auth/oauth2/NAME/loginCallback" (where NAME is the service name).
   • URL for requesting user data: "https://graph.microsoft.com/v1.0/me"
   • User field in user name answer: "userPrincipalName"
5. Click Save.

Important security note:
You can set Path for authorization and Path to get access tokens depending on the types of accounts you would like to authorize:

• "/common/oauth2/V2.0/(…)": All Microsoft accounts (personal or organizational) are allowed.
• "/consumers/oauth2/V2.0/(…)": Non-organizational accounts are allowed.
• "/organizations/oauth2/V2.0/(…)": Only organizational accounts are allowed.
• "/<tenant-id>/oauth2/V2.0/(…)": Only accounts from the specified tenant-id are allowed.
  Click this link to obtain a tenant-id. You can try using /common/ initially, and then restrict it later using /tenant-id/ if you cannot access the tenant-id upfront. You need Azure administration privileges to get your tenant-id.

Linking your users to their Microsoft account

You can now enable OAuth2 authentication for all users. Follow the steps below to link users to their Microsoft accounts:

1. Make sure that both oauth2 and basic authentications are enabled in your nodelocal.js file.
2. Go to Administration > Administration > Settings > Global settings, and change the default authentication method to oauth2.
3. Go to Administration > Administration > Users > Users, and set the authentication method of the "admin" user to DB.
   This is a safety net in case your OAuth2 configuration does not work. You can change it later.
4. Edit a test user (other than admin) to set its email to a Microsoft account for which you have valid credentials.
5. Log out and log back in with the test user. If you get an error, log in again as admin to fix the OAuth2 configuration and try again.
6. When the test is successful:
   1. log in again as admin,
   2. assign a Microsoft account email to the admin user,
   3. change the admin user to use the default authentication method (OAuth2).
7. Check all user emails and edit them, if necessary, to match each user's Microsoft account.
8. Edit your nodelocal.js file, and enable oauth2 only.
   Restart the Web server: your server is now safely configured to authenticate all users, including admin, with their Microsoft accounts.

Note: We recommend that you use an external identity service such as LDAP or OAuth2 for all users, including special users that support web service calls. However, you will need to adapt your web service clients to authenticate with OAuth2.

If you are using web services published by Sage X3, you can temporarily activate both basic and OAuth2 in your nodelocal.js file, and configure the special web service users to use basic authentication. This will allow you to keep your web services in operation while you adapt them for OAuth2. Once you have upgraded your web service clients, you should edit nodelocal.js again, and only enable OAuth2 to tighten the security.

Logging In with OAuth2

1. Click the OAuth2 button on the login screen.
   You can also add a direct link (http://www.my_server.com/auth/oauth2/Microsoft/loginStart) to your bookmarks and use it to log in.
2. Once redirected to the Microsoft site, authenticate using your Microsoft account, if not already done.
   
3. When prompted to, allow Sage X3 to access your Microsoft profile when logging in for the first time.
   

Note: You will be authenticated until you log out of your Microsoft account, or until you clear your browser’s cookies. As a result, Sage X3 may not ask you to authenticate each time.