Examples

Nginx Configuration

server {
        listen 80;
        listen [::]:80;
        listen 443 ssl;
        listen [::]:443 ssl;
        ssl_certificate /your/certificate/fullchain.pem;
        ssl_certificate_key /your/certificate/privkey.pem;

        client_max_body_size 200M;
        client_body_buffer_size 128k;

        server_name your.server.url;

        proxy_connect_timeout 300;
        proxy_send_timeout 300;
        proxy_read_timeout 300;
        send_timeout 300;

        location / {
                # If using Cloudflare
                proxy_set_header X-Forwarded-Host $http_cf_connecting_ip;

                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto http;
                proxy_pass http://127.0.0.1:53842;
        }



        # Always redirect to https
        if ( $scheme = http ) {
                return 301 https://$server_name$request_uri;
        }
}

OpenID Connect Configuration

Authelia

Server Configuration

Note

This guide has been written for version 4.37.5

See the Authelia documentation on how to setup an OIDC server. An example file would be as followed:

identity_providers:
  oidc:
    hmac_secret: noz1Aow6Soo9lieyus2E_EXAMPLE_KEY
    issuer_private_key: |
      -----BEGIN PRIVATE KEY-----
      ohf2shae1bahph7ahSh1
      EXAMPLE_KEY
      EP3EihoPhei9iingai0v==
      -----END PRIVATE KEY-----
    access_token_lifespan: 1h
    authorize_code_lifespan: 1m
    id_token_lifespan: 1h
    refresh_token_lifespan: 90m
    enable_client_debug_messages: false
    enforce_pkce: public_clients_only
    cors:
      endpoints:
        - authorization
        - token
        - revocation
        - introspection
      allowed_origins:
        - "https://*.your.domain"
      allowed_origins_from_client_redirect_uris: false
    clients:
      - id: gokapi-dev
        description: Gokapi Example
        secret: 'AhXeV7_EXAMPLE_KEY'
        sector_identifier: ''
        public: false
        authorization_policy: one_factor
        consent_mode: pre-configured
        pre_configured_consent_duration: 1w
        audience: []
        scopes:
          - openid
          - email
          - profile
          - groups
        redirect_uris:
          - https://gokapi.website.com/oauth-callback
        userinfo_signing_algorithm: none

• Set authorization_policy to two_factor to use OTP or a hardware key.

• If consent_mode is pre-configured, the user has the option to remember consent. That way you can use a lower Recheck identity interval in Gokapi. Logout through the Gokapi interface will not be possible anymore, unless the user logs out their Authelia account. If the option is set to explicit, the user always has to grant the permission after the Recheck identity interval has passed

• scopes may exclude groups if these are not required for authentication, e.g. if all users registered with Authelia may access Gokapi.

• Make sure redirect_uris is set to the correct value

Gokapi Configuration

Gokapi Configuration	Input	Example
Provider URL	URL to Authelia Server	https://auth.autheliaserver.com
Client ID	Client ID provided in config	gokapi-dev
Client Secret	Client secret provided in config	AhXeV7_EXAMPLE_KEY
Admin email address	The email address for the super-admin	gokapi@example.com
Recheck identity	If mode is pre-configured, use a low interval	12 hours
Restrict to group	Check this, if only users from certain groups shall be allowed to access Gokapi admin menu	checked
Scope identifier (group)	Use a scope that lists the user’s groups	groups
Authorised groups	Enter all groups, separated by semicolon * can be used as a wildcard	dev;admins;gokapi-*
Only allow existing users	Check this, if you do not want authenticated users to automatically create a new account or restore a deleted one	unchecked

Keycloak

Note

This guide has been written for version 24.0.3

Warning

In a previous version of this guide, the client mapping was for the predefined mapper “Group memberships”, which in some cases always returned the value “admin”. Please make sure that you are using a custom mapper, as described in Addding a scope for exposing groups (optional)

Server Configuration

Creating the client

1. In your realm (default: master) click on [Manage] Clients and then Create Client

   • Client Type: OpenID Connect

   • Client ID: a unique ID, gokapi-dev is used in this example

2. Click Next

   • Set Client authentication to on

   • Only select Standard flow in Authentication flow

3. Click Next, add your redirect URL, e.g. https://gokapi.website.com/oauth-callback and click Save

4. Click Credentials and note the Client Secret

Addding a scope for exposing groups (optional)

1. In the realm click on [Manage] Client Scopes and then Create Client Scope

   • Name: groups

   • Type: Default

   • Protocol: OpenID Connect

   • Click Save

2. Click Mappers

   • Click Add mapper

   • Select Configure a new mapper

   • Select Group Membership

   • Enter a name and set Token Claim Name to a claim name, e.g. groups

   • Deselect Full group path if you are only using a single realm. Otherwise use the full name for your groups in the Gokapi configuration, e.g. /admins instead of admins

   • Click Save

3. In the realm click on [Manage] Clients and then gokapi-dev

   • Click Client Scopes

   • Click Add Client Scope

   • Select the new scope and click Add / Default

Gokapi Configuration

Gokapi Configuration	Input	Example
Provider URL	URL to Keycloak realm	http://keycloak.server.com/realms/master
Client ID	Client ID provided	gokapi-dev
Client Secret	Client secret provided	AhXeV7_EXAMPLE_KEY
Recheck identity	If open Consent required is disabled, use a low interval	12 hours
Admin email address	The email address for the super-admin	gokapi@example.com
Restrict to group	Check this, if only users from certain groups shall be allowed to access Gokapi admin menu	checked
Scope identifier (group)	Use a scope that lists the user’s groups	groups
Authorised groups	Enter all groups, separated by semicolon * can be used as a wildcard	dev;admins;gokapi-*
Only allow existing users	Check this, if you do not want authenticated users to automatically create a new account or restore a deleted one	unchecked

Note

Logout through the Gokapi interface will not be possible anymore, unless the user logs out their Keycload account.

Google

Server Configuration

Note

This guide has been last updated in January 2024 and is based on this documentation

1. Go to the Google Cloud Platform Console.

2. From the projects list, select a project or create a new one.

3. If the APIs & services page isn’t already open, open the console left side menu and select APIs & services.

4. On the left, click Credentials.

5. Click New Credentials, then select OAuth client ID.

6. Select Application Type Webapplication

7. Add the correct Gokapi redirect URL and click Create

Gokapi Configuration

Gokapi Configuration	Input	Example
Provider URL	https://accounts.google.com	https://accounts.google.com
Client ID	Client ID provided	XXX.apps.googleusercontent.com
Client Secret	Client secret provided	AhXeV7_EXAMPLE_KEY
Recheck identity	Use a low interval	12 hours
Admin email address	The email address for the super-admin	gokapi@example.com
Restrict to group	Unsupported	unchecked
Only allow existing users	Check this, if you do not want authenticated users to automatically create a new account or restore a deleted one	unchecked

Microsoft Entra / Azure

Server Configuration

Note

This guide has been last updated in February 2024

Creating the client

1. Open https://entra.microsoft.com/

2. Go to Applications / App registration / New registration

3. Enter name and for redirect values Web and the Gokapi redirect URL shown in the setup

4. In Manage / Authentication / Implicit grant and hybrid flows check ID Tokens

5. In Certificate & secrets / Client secrets click New client secret, enter the value of the secret in Gokapi setup

6. In Application / API permissions / click Grant admin consent.

7. The client ID shown in Application Overview / Application (client) ID

8. The provider URL is https://login.microsoftonline.com/REALM/v2.0/, replace REALM with the tenant id shown in Application Overview / Directory (tenant) ID (see also https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc for other options)

Optional: Restricting Gokapi to specific users or groups:

1. Open https://entra.microsoft.com/

2. Go to Applications / Enterprise Applications and select Gokapi

3. Go to Manage / Properties and check Assignment required?

4. Go to Manage / Users & Groups and add the allowed users / groups

Gokapi Configuration

Gokapi Configuration	Input	Example
Provider URL	https://login.microsoftonline.com/REALM/v2.0/, replace REALM	https://login.microsoftonline.com/abcdef-1234-4678-9540-abcdefabcdef/v2.0/
Client ID	Client ID provided	11111122222-4444-55555-66666-abcdefabcdef
Client Secret	Client secret provided	ach5sho3Ru-Heop7aMaez-example
Admin email address	The email address for the super-admin	gokapi@example.com
Recheck identity	Use a low interval	12 hours
Restrict to group	Unsupported	unchecked
Only allow existing users	Check this, if you do not want authenticated users to automatically create a new account or restore a deleted one	checked