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 use the [email protected] mock account.
  • Choose 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.
  • Configure Oauth2 as a valid authentication method in your Sage X3 nodelocal.js file:
    session: {
    timeout: 30, // minutes
    checkInterval: 60, // seconds
    auth: ["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 need it later 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/loginCallback where 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:
  5. Click Save.

Important security note

You can set the Path for authorization and Path to get access token with several options:

  • /common/oauth2/V2.0…: Enables all Microsoft accounts
  • /consumers/oauth2/V2.0…: Allows non organizational accounts
  • /organizations/oauth2/V2.0…: Only allows organizations' accounts
  • //oauth2/V2.0…: Only allows accounts from the specified tenant-id

To obtain the tenant-id, see http://stackoverflow.com/questions/26384034/how-to-get-the-azure-account-tenant-id. You can try first with /common/ and restrict later with /tenant-id/ if you can't access the tenant-id. You need Azure admin privilege to do so.

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.