Authority Service

The authority service is responsible for managing all OpenID® Connect flows to the various authentication providers and creating and processing the access tokens which contain the claims of the user/client.

Minimum requirements

Login to the server where you installed the Autority Service and ensure that this server meets the minimum system requirements of an Ometa Framework server.

Application pool and IIS site

  • Ensure an application pool and an IIS site mapped to the %OMETA_INSTALLATION_MAP%/Services/Authority Service directory.
  • Ensure an HTTPS binding to the site with a port of your choice, a valid hostname and ensure that a valid SSL certificate is chosen.

Create IIS Site

Warning

The port of Authority Service Url in the database must match the port in IIS. If the ports don't match, update Authority Service Url of table dbo.Config from the Ometa Business Connector database (default name is Ometa Business Connector) to the correct port.

  • The user of the application pool should be an AD account. It should be able to contact the Active Directroy server. It needs access the logging directory (default: %OMETA_INSTALLATION_MAP%\Log\Services) and its own website directory. This account should also have read / write access to the Ometa Framework database, especially when trusted connections are used.

Application Pool Identity

Configure Database Connection string

Note

This section can be ignored from v5.0 as the connection strings will be automatically configured in the installer. However, this is still required for older versions, or when upgraded from an older version.

Setup the connection string to the Ometa Framework database by opening up the appsettings.json in the %OMETA_INSTALLATION_MAP%/Services/Authority Service map and adding/updating the value of ConnectionStrings.OmetaFrameworkDatabase, and .

{
  // ...
  // Other JSON Settings
  // ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source=dbserver.ometa.net;database=framework database;trusted_connection=yes;",
    "OmetaDcsDatabase": "Data Source=dbserver.ometa.net;database=dcs database;trusted_connection=yes;"
  }
}
Warning

This is a JSON file. Any special characters in the connection strings should be escaped. The most common use case for escaping characters is named SQL instances. Normally you would write Data Source=myserver\mysqlinstance but as this is JSON, the backslash should be escaped: Data Source=myserver\\mysqlinstance.

Note

This connection string will be used by the Framework Authority Service for both accessing and migrating (creating new tables) the database to the latest schema of the installed framework version. Make sure that the database name in the connection string is the same as the database name from the SQL server. Ensure that the user in the connection string has enough access rights to completely manage the database.

If you set trusted_connection to yes, the user of the application pool will be used for those actions.

Azure SQL Database connection strings

When using Azure SQL Database services for data storage, adapt the connection strings a bit:

{
  // ...
  // Other JSON Settings
  // ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source='tcp:your-azure-instance-sql.database.windows.net,1433';database=framework database;Uid=sqlaccount;Pwd=sqlpwd;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;",
    "OmetaDcsDatabase": "Data Source='tcp:your-azure-instance-sql.database.windows.net,1433';database=dcs database;Uid=sqlaccount;Pwd=sqlpwd;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;"
  }
}

Replace your-azure-instance-sql.database.windows.net, sqlaccount and sqlpwd with the proper corresponding values.

Configure the signing certificate

To provide users & clients with tokens, the authority service needs a valid certificate to sign those tokens. The easiest way to setup this signing certificate is to copy/paste the distinguished name of the certificate you want to use for this in the appsettings.json file.

Tip

Certificates can be found by doing the following:

  1. Open Windows Start
  2. Search Manage Computer Certificates
  3. Navigate to the certificate that is used in IIS (e.g. Trusted Root Certificates/Certificates)
  4. Open your certificate

Certificate Distinguished Name

{
  // ...
  // Other JSON Settings
  // ...
  "SigningCertificate": "CN=services.ometa.net",
  // ...
  // Other JSON Settings
  // ...
}
Warning

The distinguished name in the appsettings.json file needs to be 100% correct or it cannot be found. Even a misplaced space in the name can mess up the configuration. Check the tip below in those cases.

Tip

If you experience issues with setting up the signing certificate, you should look into the log file of the Authority Service (check the troubleshooting section). Upon starting the Authority Service, it will log all the distinguished names of the certificates it can use to this log file. However, this does not mean that those certificates are valid. It just means that they can be found by the Authority Service.

2019-02-07 14:37:02.8409334 [Information-1]: Possible certificate: CN=*.ometa.net, O=Ometa, L=Wommelgem, C=BE
2019-02-07 14:37:02.8411791 [Information-1]: Possible certificate: CN=services.ometa.net
2019-02-07 14:37:02.8412320 [Information-1]: Possible certificate: CN=localhost

Configure Allowed Origins

Provide the allowed origins from which the core service may accept requests:

{
  // ...
  // Other JSON Settings
  // ...
  "AllowedOrigins": [ "https://example.sharepoint.com" ]
}
Note

You can pass multiple origins. You can also pass a wildcard for subdomains, for example: 'https://*.sharepoint.com'.

Enabling LDAPS Support for AD

The authority service can connect to AD via LDAP to add properties and groups as claims. Usually the service connects via the default LDAP protocol on port 389. However due to security reasons a shift is being made to use LDAPS (LDAP over SSL) connections.

Enabling such connections can be done via configuration in the appsettings.json. The DomainPath setting must have the port number 636 in the path, otherwise the authority service will not recognise that LDAPS should be used.

{
  // ...
  // Other JSON Settings
  // ...
  "LdapConfiguration": {
    "DomainPath": "LDAP://:636"
  }
}

The example setting above tells the authority service to use the AD settings as defined on the domain joined machine / server but connect over LDAPS.

Configuring SAML 2.0 Assertions

The authority service is capable of creating SAML 2.0 assertions for provided access tokens. The OData service already implements this functionality when required.

This is a full example of the settings that can be configured in the appsettings.json of the Authority Service regarding SAML 2.0 assertions.

{
  // ...
  // Other JSON Settings
  // ...
  "Saml2Assertions": {
    "Issuer": "Ometa Authority Service",
    "Subject": {
      "NameIdentifierRegexToClear": "(.*\\\\)",
      "NameIdentifierFormatUri": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
      "Confirmations": [
        {
          "MethodUri": "urn:oasis:names:tc:SAML:2.0:cm:bearer",
          "RecipientUri": "https://oauth.services.net/connect/token"
        }
      ]
    },
    "Conditions": {
      "AudienceRestrictions": [
        "DEVELOPERS",
        "ADMINS"
      ]
    },
    "Statements": {
      "AuthenticationStatements": [
        {
          "ClassReferenceUri": "urn:none",
          "DeclarationReferenceUri": "urn:none"
        }
      ]
    }
  }
}

Issuer

If not configured, the issuer will be Ometa Authority Service.

<saml:Assertion ID="_a11a62e1-70bf-4509-8e17-88cc0559a73e" IssueInstant="2021-02-19T12:22:27.931Z" Version="2.0" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml:Issuer>Ometa Authority Service</saml:Issuer>
</saml:Assertion>

Subject

The name identifier in the SAML 2.0 assertion will be filled in with the provider key found in the access token of the current user. For Windows AD, this will be DOMAIN\Username, for other providers like Microsoft O365, this can be an email address.

If your OAuth token provider needs to strip off some information of the default name identifier, you can replace it with a regex configured in the NameIdentifierRegexToClear setting.

For example: to strip off the domain of the user OMETA\ometauser, you can set (.*\\) on NameIdentifierRegexToClear. The result in the SAML 2.0 assertion will be:

<saml:Subject>
    <saml:NameID>ometauser</saml:NameID>
</saml:Subject>

Other Settings

The identifier format uri to set in the name identifier. In our example urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">ometauser</saml:NameID>

Claims in Access Token

All claims present in the access token of the user will be set as attribute values in the SAML 2.0 assertion.

<saml:AttributeStatement>
    <saml:Attribute Name="nameidentifier">
        <saml:AttributeValue>OMETA\ometauser</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="surname">
        <saml:AttributeValue>ometa</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Nam964e="givenname">
        <saml:AttributeValue>user</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="name">
        <saml:AttributeValue>ometa user</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="adgroup.id">
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-1089</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-1092</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-1091</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-13659</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-45315</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-42847</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-31025</saml:AttributeValue>
        <saml:AttributeValue>S-1-5-33-54864598-2165198845-54657651-513</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="adgroup">
        <saml:AttributeValue>OMETA\Admins</saml:AttributeValue>
        <saml:AttributeValue>OMETA\Developers</saml:AttributeValue>
        <saml:AttributeValue>OMETA\Domain Users</saml:AttributeValue>
        <saml:AttributeValue>Everyone</saml:AttributeValue>
        <saml:AttributeValue>BUILTIN\Users</saml:AttributeValue>
        <saml:AttributeValue>NT AUTHORITY\NETWORK</saml:AttributeValue>
        <saml:AttributeValue>NT AUTHORITY\Authenticated Users</saml:AttributeValue>
        <saml:AttributeValue>NT AUTHORITY\This Organization</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="emailaddress">
        <saml:AttributeValue>ometauser@ometa.net</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>
Note

The only data that is always present in the SAML 2.0 assertion are issuer and the nameid of the subject. If another setting is not present in the configuration, it will be left out in the SAML 2.0 assertion.

Warning

The SAML 2.0 assertion will be signed with the certificate you configured in the step configure the signing certificate. Ensure that your OAuth token provider trusts this certificate.

Test the Authority Service

Tip

Always restart the Authority Service when changing settings in the appsettings.json file.

Test the Authority Service by navigating to https://your-site-binding:port. This should succeed without a security warning from the browser. Note that the "Click here to test your login" won't work yet.

Authority Service Success

Logging

  • If anything goes wrong when testing the service and you get an error page similar like the one below, your best bet is to check any log files in the BAM log directory, default directory %OMETA_INSTALLATION_MAP%/Log.
  • If BAM is enabled on the directory where the logging takes place, it is also possible that BAM already processed the log file. In that case, you'll need to check the BAM portal. Look for a process with the name Ometa.Framework.Authority.
  • When the above does not solve the issue, check Application Pools identity. (see Application Pool and IIS-Site)

Service Start Failure

When checking the log file, you'll need to search for a fatal error for example.

2019-02-07 08:55:39.4045121 [Fatal-1]: Application startup exception
    System.InvalidOperationException: certificate: 'CN = services.ometa.net' not found in certificate store

Routing Multiple Service Instances

In some more advanced use cases where the Ometa framework has different data sources that cannot be accessed by the same Core service (like internal active directory), or providing data on multiple SharePoint environments, there can be a need to use multiple Core services originating from one framework installation.

This configuration is possible in the database ConfigDiscovery table. A new entry in this table can be created with the url of another Core service, generic REST or authority service.

Tip

Empty configurations will be ignored and use the default value from the Config table.

By creating and linking this entry to a ConditionSet, different conditions can be used to select a different service instance.

The following fields can be used to define the conditions on the discovery:

Name FieldType Description
Request.IsExternalUser YesNo Indicates if the user is from outside the organisation. This field can only be true on SharePoint Online environments external users. For example, this field can never be true when connecting the Ometa Business Connector.
Request.Url Text The target url of the request. This is the Ometa authority service itself.
Request.IpAddressV4 Text The IP-address v4 of the user.
Request.IpAddressV6 Text The IP-address v6 of the user.
Request.UserAgent Text The user agent of the user.
Request.Host Text The host of the url.
Request.Referer Text The original address the request came from. This can be used to determine the SharePoint environment.
Request.AcceptLanguage Text The languages client can understand, and which variant is preferred.
Tip

The available fields and their values can be validated in the logging of the core service upon discovery (either manual or by an ADM). The minimum log level for this is 'Information'.

Troubleshooting

HTTP 502.5 - ANCM Out-Of-Process Startup Failure

If you encounter a 'HTTP 502.5 - ANCM Out-Of-Process Startup Failure' error when testing the service, this is mostly caused by the fact that you just installed the .Net Core runtime and IIS is not yet restarted. Open up a command prompt as administrator and execute an iisreset.

Important

It is not enough to restart IIS via the management tool. You really have to execute an iisreset command. If that doesn't solve the issue, you can also try to completely reboot the server.

Make sure your settings in the appsettings.json file are correct and your application pool identity has enough access rights to the database if you use trusted connection in the connection string.

502.5 Error

Tip

Most common causes for fatal errors:

  • Invalid appsettings.json (remember that a backslash needs to be escaped by another backslash)
  • Distinguished name misspelled or belongs to a certificate which cannot be found
  • Invalid or missing connection string
  • Invalid or missing log configuration
  • Not enough access rights to the database
  • Not enough access rights to the log directory

An Error Occurred While Starting The Application

If you encounter 'An error occured while starting the application'. Check that your IIS Application Pools and sites are configured correctly.

Service Start Failure

Other (fatal) errors

Some errors are thrown too early to be caught by the logging structures (ex: initializing the logging itself). In this case the only way to see those errors is to start the service outside of IIS (in-process) with the dotnet CLI.

  1. Open up a command prompt as an administrator and navigate to the %OMETA_INSTALLATION_MAP%/Services/Authority Service directory
  2. Execute the command dotnet .\Ometa.Framework.Authority.dll

Any errors within the startup sequence will be thrown to the console and can be investigated.

Dotnet CLI

If the command above executes succesfully but browsing the service still returns 'HTTP 500.19 Internal Server' error, ensure that the .NET Core Runtime is explicitly installed.

Warning

Installation of the .NET Core SDK does not install all required modules to host the service on IIS.

Browser fails to challenge (cannot reach this page)

If you have Windows Authentication enabled on the Authority Service and the user is outside your network domain, it can happen that the browser states that the page cannot be reached when the user is forwarded to the Authority Service for authentication.

Cannot reach page

So far, this behavior has only been seen on Edge browsers.

Follow these steps to ensure that the browser tries to prompt the user for credentials rather then ignoring the challenge.

  1. Go to the Authentication settings of the Authority Service.
  2. Right-click Windows Authentication and click Providers.
  3. Make sure that NTLM takes precedence over Negotiate.

Windows auth providers

Keyset does not exist

Refer to the troubleshooting of Ometa Business Connector.

IDX10630: The '[PII is hidden]' for signing cannot be smaller than '[PII is hidden]' bits. KeySize: '[PII is hidden]'. Parameter name: key.KeySize

Refer to the troubleshooting of Ometa Business Connector.