ADFS/SINGLE SIGN ON

Introduksjon

Mikromarc 3 støtter autentisering av Active Directory brukere ved hjelp av AD FS (Active Directory Federation Server) ved hjelp av OAuth 2.

Denne artikelen beskriver hvordan en AD FS (Active Directory Federation Server) server og Mikromarc database skal konfigureres for å kunne bruke Active Directory som innloggingstjener.

Dokumentet beskriver IKKE hvordan AD FS installeres, dette er ganske rett fram installasjon via Windows.

Systemkrav

• Active Directory Domene
• Windows Server 2012R2 eller nyere
• AD FS 3.0 eller nyere
  • En del av Windows Server 2012R2

Mikromarc 3 konfigurasjon av AD FS

Konfigurasjon på AD FS server er todelt, en for selve AD FS og en for å tillate OAuth 2 anrop.

AD FS

Tekst i "" er navn på elementer som vises på skjerm. Tekst som er Italic er tekst som skal legges inn.

1. Åpne "AD FS Management"

2. Gå til "Trust Relationships"->"Relying Party Trusts"

3. Velg "Add Relyin Party Trust..." under "Actions" -> "AD FS"

4. I "Select Data Source" velg "Enter data about the relying party manually" 5. I "Specify Display Name" angi ett beskrivende navn (f.eks. Mikromarc 3)

1. Legg inn evt. "Notes" om ønskelig

6. Gå videre til "Configure Identifiers" og legg til urn:mikromarc.no:mikromarc3client i "Relying party trust identifier" og klikk "Add"

7. Gå videre til "Finish" og marker "Open the Edit Claim Rules Dialog for this relying party trust when the wizard closes"

8. I "Edit Claim Rules for <xxx>" klikk "Add Rule..."

9. Under "Choose Rule Type" velg "Send LDAP Attributes as Claims" i "Claim rule template"

10. I "Configure Claim Rule"

1. Gi ett beskrivende navn i "Claim rule name"
2. Velg "Active Directory" i "Attribute Store"
3. I "Mapping of LDAP attributes to outgoing claim types" legg til en claim

• "LDAP Attribute" velg ett attributt som identifiserer brukere unikt. Eksempler på hva som kan bli brukt:
  • SAM-Account-Name er brukernavnet på en person, dette er IKKE unikt over ulike domener
  • User-Principal-Name er fullstendig navn + domene (i formatet: <brukernavn>@<domene>), dette er unikt over ulike domener
• "Outgoung Claim Type" velg UPN

Nå er AD FS server konfigurert for å kunne autentisere en innloggingstjener

OAuth 2

Konfigurasjon av OAuth 2 gjøres via PowerShell via en PowerShell kommando: Add-ADFSClient -Name "OAuth for Mikromarc 3" -ClientId "da5b4b3d-ddb5-4a29-9f62-60b675e85a82" -RedirectUri "http://mikromarc.no/mikromarc3/oauth_callback"

Refresh Token

Per i dag bruker ikke Mikromarc 3 refresh tokens, men det kan være at dette kommer til å bli aktuelt senere så for å forberede dette kan følgende PowerShell kommando kjøres: Set-AdfsRelyingPartyTrust -TargetName "<Det navn som ble gitt tidligere i punkt 5>" -IssueOAuthRefreshTokensTo AllDevices

Aktiver Forms authentication for intranet løsninger

OBS: Bør bare gjøres om Windows Authentication IKKE fungerer, ellers la standard innstillinger være som de er.

I visse tilfeller fungerer det ikke å kjøre Windows Authentication som autentiseringsregel på ADFS serveren, så derfor må man tvinge frem Forms Authentication.

1. Åpne "AD FS Management"
2. Gå til "Authentication Policies"
3. Velg "Edit Global Primary Authentication..." under "Actions" -> "Authentication Policies"
4. Under Intranet, aktiver Forms Authentication og ta bort Windows Authentication

Mikromarc 3 konfigurasjon opp til 6.70

All Single SignOn konfigurasjon ligger i Mikromarc i property systemet under UNIT.

All konfigurasjon kan ligge under enhet 0, men alt foruten "Active" flagget kan også legges per enhet om man ønsker å ha ulike inloggings steder for ulike enheter i databasen.

Konfigurasjonen ligger under UNIT\<ENHETID>\SSO

Følgende er gyldige konfigurasjonsparametere:

• Active
  • OBS: BARE gyldig under enhet 0
  • Sett til True eller 1 om databasen støtter SSO
• ServerUrl
  • Må settes
  • Kan settes per enhet, men går også på enhet 0
  • URL til AD FS server
  • Eksempel: https://<somedomain>/adfs
• IgnoreCertificateErrors
  • Valgfri
  • Kan settes per enhet
  • Sett til True eller 1 om sertifikat feil skal ignoreress
  • OBS!!! DET BLIR SETT PÅ SOM ETT STORT SIKKERHETSPROBLEM Å KJØRE AD FS MED SELF-SIGNED ELLER UTEN GYDLIG SSL SERTIFIKAT!!
• ADFSSigningCertificate
  • Valgfri
  • Kan settes per enhet
    • OBS: Om ServerUrl er på enhetsnivå må denne også (om nødvendig) settes per enhet
  • Skal settes til en BASE64 Encoded streng av sertifikatet, dette kan finnes ved å følge disse steg:

1. Via en webleser gå til https://<server dns>/FederationMetadata/2007-06/FederationMetadata.xml

2. I XML dokumentet finn "RoleDescriptor" med type "fed:SecurityTokenServiceType" og underelmentet "KeyDescriptior" med "use" satt til "Signing"

3. Under dette elementet kopier inneholdet av "X509Certificate" elementet og legg inn i "ADFSSigningCertificate"

• ADFSSigningCertificateIssuer
  • Valgfri
  • Kan settes per enhet
    • OBS: Om ADFSSigningCertificate er satt MÅ denne også settes
• Skal settes til en streng som identifierer Issuer, detta kan finnes ved å følge disse steg:

1. Via en webleser gå til https://<server dns>/FederationMetadata/2007-06/FederationMetadata.xml

2. I XML dokumentet på første elementet ("EntityDescriptor") finn "EntityID" og legg verdien av dette i "ADFSSigningCertificateIssuer"

VIKTIG: OM ikke "ADFSSigningCertificate" settes, så vil Mikromarc prøve å lese sertifikatet fra server. Det er anbefalt å IKKE sette "ADFSSigningCertificate"/"ADFSSigningCertificateIssuer" og la Mikromarc ta seg av hentingen av dette, men i visse miljøer der AD FS server ikke er tilgjengelig for Mikromarc server, så må "ADFSSigningCertificate"/"ADFSSigningCertificateIssuer" settes.

Mikromarc configuration in version 6.75 or higher

The AD FS configuration for Mikromarc is done in the property system of Mikromarc and is identical both for Mikromarc 3 and Mikromarc Plus.

The configuration for AD FS is placed in "SYSTEM" in the folder "SSO" and is common for all units. If a customer with multiple units wants multiple AD integrations this must be done on AD FS server. The following configuration parameters exists:

• SSO
  • Active
    • True or 1 to activate SSO
  • ADFS
    • Display Name
      • Optional
      • Set this to a describing name for the Active Directory authentication and it will be displayed in the login page for Mikromarc Plus.
      • Defaults to local translation of "Active Directory" if not specified
    • ServerURL
      • REQUIRED
      • Specify the Url to the AD FS Server, eg. https://<somedns>/adfs

AD FS 3.0 OAuth 2.0 configuration

Step-by-step configuration

AD FS Configuration

Run each of these steps once for Mikromarc 3 and once for Mikromarc Plus

1. Open "AD FS Management"
2. Navigate to "Trust Relationships" -> "Relying Party Trusts"
3. Select "Add Relying Party Trust..." under "Actions" -> "Relying Party Trusts" to open the "Add Relying Party Trust Wizard"
4. On "Welcome"
   1. Click "Start"
5. On "Select Data Source"
   1. Select "Enter data about the relying party manually"
   2. Click "Next >"
6. On "Specify Display Name"
   1. Enter a describing "Display Name"
   2. Click "Next >"
7. On "Choose Profile"
   1. Ensure that "AD FS profile" is selected
   2. Click "Next >"
8. On "Configure Certificate"
   1. Click "Next >"
9. On "Configure URL"
   1. Click "Next >"
10. On "Configure Identifiers"
    1. Specify the "Relying party trust identifier

• • For Mikromarc 3: urn:mikromarc.no:mikromarc3client
  • For Mikromarc Plus: urn:mikromarcplus.com:oauth

1. 1. Click "Add"
   2. Click "Next >"
2. On "Configure Multi-factor Authentication Now?"
   1. Configure this if it is needed, Mikromarc does not need this

• • If not needed, ensure that "I do not want to configure multi-factor authentication settings for this relying party trust at this time." is selected.

1. 1. Click "Next >"
2. On "Choose Issuance Authorization Rules"
   1. Ensure that "Permit all users to access this relying party" is selected.
   2. Click "Next >"
3. On "Ready to Add Trust"
   1. Click "Next >"
4. On "Finish"
   1. Ensure that the "Open the Edit Claim Rules dialog for this relying party trust when the wizard closes" is checked.
   2. Click "Close"
5. The "Add Transform Claim Rule Wizard" will open
6. On the "Issuance Transform Rules" tab
   1. Click "Add Rule..."
7. The "Add Transform Claim Rule Wizard" will open
8. On "Select Rule Template"
   1. Select "Send LDAP Attributes as Claims" in "Claim rule template"
   2. Click "Next >"
9. On "Configure Rule"
   1. Enter a "Claim rule name" for this claim rule (e.g. the claim name (see below))
   2. Select "Active Directory" in "Attribute store"
   3. In "LDAP Attribute" select the Active Directory attribute that uniquely identifies a user in the Active Directory
   4. In "Outgoing Claim Type" select the "Required Claim"

• • For Mikromarc 3: UPN
  • For Mikromarc Plus: Name

1. 1. Click "Finish"
2. Click "OK"

Enabling OAuth authentication on AD FS

1. Open a power shell as administrator
2. Execute the following command (with the specified parameters below)
   1. Add-ADFSClient -Name "Mikromarc" -ClientId "<ClientId>" -RedirectUri <Redirect URI>
      1. ClientId: The <database name>
         1. The database name can be obtained by looking at the configuration entry for the customer in Mikromarc 3
      2. Redirect URI:
         1. Mikromarc 3 only: "http://mikromarc.no/mikromarc3/oauth_callback"
         2. Mikromarc Plus only: "<URL to Mikromarc Plus for customer>/signin-adfs"
            1. The <URL to Mikromarc Plus for customer> depends on the environment and configuration of Mikromarc Plus
               1. Customers hosted by Axiell norge: https://<database name>.mikromarcplus.com
               2. Local customer environment it is the URL to Mikromarc Plus in their environment
      3. Mikromarc 3 and Mikromarc Plus: Combine both in a comma separated list

AD FS force Forms Authentication

In some circumstances AD FS fails using integrated windows authentication, and thus it is required to force forms authentication.

1. Open "AD FS Management"
2. Navigate to "Authentication Policies"
3. Select "Edit Global Primary Authentication..." under "Actions" -> "Authentication policies"
4. In "Intranet" activate "Forms authentication" and remove "Windows Authentication"

NOTE: This is a global configuration and affects ALL AD FS usage, should be avoided unless necessary!

AD FS 2016 OpenID configuration

General configuration

1. Open "AD FS Management"
2. Navigate to "Application Groups"
3. Select "Add Application Group..." under "Actions" -> "Application Groups" to open the "Add Application Group Wizard"
4. On "Welcome"
   1. Specify a unique name in "Name" (e.g. Mikromarc)
   2. Optionally "Notes"
   3. Select "Server Application"
   4. Click "Next >"
5. On "Server application"
   1. In "Client identifier" specify <database name>

• The database name can be obtained by looking at the configuration entry for the customer in Mikromarc 3

1. 1. In the "Redirect URI" specify the following and click "Add" for each

• http://mikromarc.no/mikromarc3/oauth_callback
• <URL to Mikromarc Plus for customer>/signin-adfs
  • The <URL to Mikromarc Plus for customer> depends on the environment and configuration of Mikromarc Plus
    • Customers hosted by Axiell Norge: https://<database name>.mikromarcplus.com
    • Local customer environment it is the URL to Mikromarc Plus in their environment

1. 1. Click "Next >"
2. On "Configure Application Credentials"
   1. Select "Generate a shared secret", store the auto-generated secret a secure place

• Please note that this is the *ONLY* place you'll see the secret, if it is lost you'll have to regenerate it and use the new one

1. 1. Click "Next >"
2. On "Summary"

• Click "Next >"

1. On "Complete"

• Click "Close"

Mikromarc 3

1. Double-click the newly created application group (or the application group you want to add Mikromarc 3 authentication
2. Click "Add application..." to open the "Add a new application to <name>" wizard
3. Select "Web API"
4. Click "Next"
5. On "Configure Web API"
   1. Specify a unique name in "Name" (e.g. Mikromarc 3)
   2. In "Identifier"
      1. urn:mikromarc.no:mikromarc3client
   3. Click "Add"
   4. Click "Next >"
6. On "Apply Access Control Policy"
   1. Click "Next >"
7. On "Configure Application Permissions"
   1. In "Permitted scopes" select "openid"
   2. Click "Next >"
8. On "Summary"
   1. Review the configuration and go back to modify if needed
   2. Click "Next >"
9. On "Complete"
   1. Click "Close"
10. Double-click the newly created "Web API" configuration
11. Select the "Issuance Transform Rules" tab
12. Click "Add Rule..." to open the "Add Transform Claim Rule Wizard"
13. On "Select Rule Template"
    1. Select "Send LDAP Attributes as Claims" in "Claim rule template"
    2. Click "Next >"
14. On "Configure Rule"
    1. Enter a "Claim rule name" for this claim (e.g. UPN)
    2. Select "Active Directory" in "Attribute store"
    3. In "LDAP Attribute" select the Active Directory attribute that uniquely identifies a user in the Active Directory
    4. In "Outgoing Claim Type" select "UPN"
15. Click "Finish"
16. Click "OK"
17. Click "OK" to finish

Mikromarc Plus

1. Double-click the newly created application group (or the application group you want to add Mikromarc 3 authentication
2. Click "Add application..." to open the "Add a new application to <name>" wizard
3. Select "Web API"
4. Click "Next"
5. On "Configure Web API"
   1. Specify a unique name in "Name" (e.g. Mikromarc Plus)
   2. In "Identifier"
      1. urn:mikromarcplus.com:oauth
   3. Click "Add"
   4. Click "Next >"
6. On "Apply Access Control Policy"
   1. Click "Next >"
7. On "Configure Application Permissions"
   1. In "Permitted scopes" select "openid"
   2. Click "Next >"
8. On "Summary"
   1. Review the configuration and go back to modify if needed
   2. Click "Next >"
9. On "Complete"
   1. Click "Close"
10. Double-click the newly created "Web API" configuration
11. Select the "Issuance Transform Rules" tab
12. Click "Add Rule..." to open the "Add Transform Claim Rule Wizard"
13. On "Select Rule Template"
    1. Select "Send LDAP Attributes as Claims" in "Claim rule template"
    2. Click "Next >"
14. On "Configure Rule"
    1. Enter a "Claim rule name" for this claim (e.g. Name)
    2. Select "Active Directory" in "Attribute store"
    3. In "LDAP Attribute" select the Active Directory attribute that uniquely identifies a user in the Active Directory
    4. In "Outgoing Claim Type" select "Name"
    5. Click "Finish"
15. Click "OK"
16. Click "OK" to finish

Mikromarc configuration

The AD FS configuration for Mikromarc is done in the property system of Mikromarc and is identical both for Mikromarc 3 and Mikromarc Plus. The configuration for AD FS is placed in "SYSTEM" in the folder "SSO" and is common for all units. If a customer with multiple units wants multiple AD integrations this must be done on AD FS server. The following configuration parameters exists:

• SSO
  • Active
    • True or 1 to activate SSO
• ADFS
  • DisplayName
    • OPTIONAL
    • Set this to a describing name for the Active Directory authentication and it will be displayed in the login page for Mikromarc Plus
    • Defaults to local translation of "Active Directory" if not specified
  • ServerUrl
    • REQUIRED
    • Specify the Url to the AD FS Server
      • E.g. https://<somedns>/adfs
  • Secret
    • REQUIRED IN AD FS 2016 OR NEWER
    • Specify the secret stored when configuring the AD FS 2016 or newer

NOTE: This information is refreshed each hour on Mikromarc Plus, so wait/retry with periodic intervals until the new changes is reloaded to ensure that it works as expected.