====ADFS====

===Prerequisites===

To be able to follow the steps below you'll need to have Windows Server 2016 or later with the "Active Directory Federation Services (ADFS)" feature enabled. 

===Add an OpenID Connect configuration to ADFS===

  - Open the "AD FS Management" tool located under the "Tools" menu at the top right of the Server Manager.
  - Select the "Application Groups" folder item in the left sidebar.
  - Click on "Add Application Group..." in the sidebar to the right.
  - Give the application group a name, for example "OpenID Connect"
  - Select the "Server application accessing a web API" list item and click next.
  - Copy and paste the **Client Identifier** to a text file for later use.
  - In the Redirect URI field, enter and add the address to your Blocks server followed by "/rest/auth/callback". For example "https://pixi.guide/rest/auth/callback". Click next.
  - Tick the "Generate a shared secret" box. Copy and paste the **Secret** to a text file for later use. Click next.
  - Paste and add the **Client Identifier** (from step 6) as the "Identifier". Click next.
  - Select the access control policy you'd like to use and click next.
  - Make sure the box next to "openid" is ticked.
  - Click the "New scope..." button in the bottom and and give it the name "allatclaims", click OK. This scope is needed for sending additional claims such as the user's groups as roles to Blocks after authentication. 
  - Finish the wizard.

===Configure OpenID Connect to provide user groups to Blocks===

  - Open the "AD FS Management" tool located under the "Tools" menu at the top right of the Server Manager.
  - Select the "Application Groups" folder item in the left sidebar.
  - Double click on the group added earlier, then double click on the "Web API" application.
  - Select the tab named "Issuance Transform Rules".
  - Click the "Add Rule..." button at the bottom.
  - Select "Send LDAP Attributes as Claims" and click next.
  - Give the rule a name, for example "BlocksRoles".
  - Select "Active Directory" as the "Attribute Store".
  - In the table below, select "Token-Groups Unqualified Names" in the first column and type "roles" into the second column.

====Blocks specific steps====

  - Open your Blocks configuration file on your Blocks server and add the "auth" section below to the already existing "server" section. Replace the values of [BLOCKS-DOMAIN-OR-IP], [PROTOCOL], [ADFS-SERVER], [CLIENT-ID] and [CLIENT-SECRET]. [CLIENT-ID] and [CLIENT-SECRET] is the items copied and saved from the **Add a OpenID Connect configuration to ADFS** section above.
    * <code>
server:
  type: pixilab_server
  auth:
    urlResolver: null
    ajaxRequestResolver: null
    callbackUrl: http://[BLOCKS-DOMAIN-OR-IP]/rest/auth/callback
    rolesOwner: attributes
    rolesPath: roles
    clients:
      - org.pac4j.oidc.client.OidcClient:
          configuration:
            discoveryURI: [PROTOCOL]://[ADFS-SERVER]/adfs/.well-known/openid-configuration
            clientId: [CLIENT-ID]
            secret: [CLIENT-SECRET]
            clientAuthenticationMethod: client_secret_basic
            scope: openid
    servlet:
      security:
        - matchers: internalMatcher
          clients: OidcClient
          authorizers: isAuthenticated
</code>
  - Start Blocks and go to "/edit" for login.

:!: Make sure you maintain all indentation as shown above, using only spaces for indentation. Here's more about [[blocks:server_configuration_file|Blocks' configuration file]] and it syntax.

===Role Mapping===

Since the groups you've configured for your users in your windows server does not match the roles used by Blocks, you have to add role mappings to the Blocks configuration file. Do this by defining a server.auth.rolesMapping parameter where the keys are the group names of your windows server configuration and the values the roles Blocks know about. For example:
<code>
rolesMapping:
  SomeGroup1: Admin
  SomeGroup2: Manager
  SomeGroup3: Creator
  SomeGroup4: Editor
  SomeGroup5: Contributor
  SomeGroup6: Staff
</code>


====Filter the groups provided to Blocks====

In the section named **Configure OpenID Connect to provide user groups to Blocks** we add a configuration that will provide Blocks with all of the user's groups. This may not be wanted since there can be thousands of these in an already existing windows server configuration. In other cases there will exist groups that doesn't have anything to to with Blocks at all. To filter the groups provided to Blocks, follow the steps below.

===Configure OpenID Connect to provide user groups to Blocks===

  - Open the "AD FS Management" tool located under the "Tools" menu at the top right of the Server Manager.
  - Select the "Application Groups" folder item in the left sidebar.
  - Double click on the group added earlier, then double click on the "Web API" application.
  - Select the tab named "Issuance Transform Rules".
  - Remove any rules you may have already added.
  - Click the "Add Rule..." button at the bottom.
  - Select "Send Claims Using a Custom Rule" and click next.
  - Give the rule the name "StoreRoles" and paste the following into the "Custom rule" field: <code>c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("roles"), query = ";tokenGroups;{0}", param = c.Value); </code>
  - Click finish and add yet another rule.
  - Again, select "Send Claims Using a Custom Rule" and click next.
  - Give this rule the name "IssueRoles" and paste the following into the "Custom rule" field: <code>c:[Type == "roles", Value =~ "^Blocks.+"] => issue(claim = c);</code>
  - The "^Blocks.+" part is a [[https://en.wikipedia.org/wiki/Regular_expression|regular expression]] used to filter the windows groups sent to Blocks as roles. In this case we only accept the windows groups starting with "Blocks". Adjust this to meet your needs.
  - Click finish.