Uptime Kuma

Tested Versions#

• Authelia
  • v4.38.0
• Uptime Kuma
  • v1.23.11

Before You Begin#

Common Notes#

1. The OpenID Connect 1.0 client_id parameter:
   1. This must be a unique value for every client.
   2. The value used in this guide is merely for readability and demonstration purposes and you should not use this value in production and should instead utilize the How do I generate a client identifier or client secret? FAQ. We recommend 64 random characters but you can use any arbitrary value that meets the other criteria.
   3. This must only contain RFC3986 Unreserved Characters.
   4. This must be no more than 100 characters in length.
2. The OpenID Connect 1.0 client_secret parameter:
   1. The value used in this guide is merely for demonstration purposes and you should absolutely not use this value in production and should instead utilize the How do I generate a client identifier or client secret? FAQ.
   2. This string may be stored as plaintext in the Authelia configuration but this behaviour is deprecated and is not guaranteed to be supported in the future. See the Plaintext guide for more information.
   3. When the secret is stored in hashed form in the Authelia configuration (heavily recommended), the cost of hashing can, if too great, cause timeouts for clients. See the Tuning the work factors guide for more information.
3. The configuration example for Authelia:
   1. Only contains an example configuration for the client registration and you MUST also configure the required elements from the OpenID Connect 1.0 Provider Configuration guide.
   2. Only contains a small portion of all of the available options for a registered client and users may wish to configure portions that are not part of this guide or configure them differently, as such it’s important to both familiarize yourself with the other options available and the effect of each of the options configured in this section by looking at the OpenID Connect 1.0 Clients Configuration guide.

Assumptions#

This example makes the following assumptions:

• Application Root URL: https://uptime-kuma.example.com/
• Authelia Root URL: https://auth.example.com/
• Client ID: uptime-kuma
• Client Secret: insecure_secret
• Secured Resource URL: https://application.example.com/

Important Notes#

This implementation has several facets which must be configured as a security precaution. It’s advised people read the OAuth 2.0 Bearer Token Usage integration guide in addition to this guide to properly understand this process.

For example this guide has a requirement to adapt a fairly new and special section of Authelia. It’s important to take the time to understand it before you attempt to do it. Some notes about this are below.

1. The implementation value of the server authz endpoints section must be the appropriate implementation for your proxy.
2. The endpoint_name in the server authz endpoints section is the actual name of the endpoint which must be configured in your proxy for the Forwarded / Redirected Authorization Flow:
   1. You can customize this name but by configuring just one all other default endpoints for authorization are removed such as /api/verify, /api/authz/forward-auth, etc.
   2. The name represents the endpoint path, for example setting endpoint_name will configure an endpoint at /api/authz/endpoint_name.
3. The use of the HeaderAuthorization strategy and how it’s configured here accepts bearer tokens in the Authorization header as one of the possible ways to authenticate, but still allows cookie-based authorization.

See more information about the server authz endpoints section in the Configuration Guide and Reference Guide.

Configuration#

Authelia#

The following YAML configuration is an example Authelia client configuration for use with Uptime Kuma which will operate with the above example:

server:
  endpoints:
    authz:
      endpoint_name:
        implementation: ''
        authn_strategies:
          - name: 'HeaderAuthorization'
            schemes:
              - 'Basic'
              - 'Bearer'
          - name: 'CookieSession'
access_control:
  rules:
    - domain:
      - 'application.example.com'
      subject: 'oauth2:client:uptime-kuma'
      policy: 'one_factor'
identity_providers:
  oidc:
    ## The other portions of the mandatory OpenID Connect 1.0 configuration go here.
    ## See: https://www.authelia.com/c/oidc
    clients:
      - client_id: 'uptime-kuma'
        client_name: 'Uptime Kuma'
        client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng'  # The digest of 'insecure_secret'.
        public: false
        scopes:
          - 'authelia.bearer.authz'
        audience:
          - 'https://application.example.com/'
        grant_types:
          - 'client_credentials'
        requested_audience_mode: 'implicit'
        token_endpoint_auth_method: 'client_secret_basic'

Notes:

• The configuration has a requested_audience_mode value of implicit which is used to automatically grant all audiences the client is permitted to request, the default is explicit which does not do this and the client must also request the audience using the audience form parameter. As Uptime Kuma does not currently support this configuration is required.
• The audience (or multiple) is the endpoints of the secured resource you want to monitor using Uptime Kuma.
• The oauth2:client:uptime-kuma is a special subject which refers to the uptime-kuma client id and allows Access Tokens granted via the Client Credentials Flow to be used provided they were granted to this client.

Application#

To configure Uptime Kuma to utilize Authelia as an OpenID Connect 1.0 Provider:

1. Create a new status monitor or configure an existing one
2. Choose monitor type e.g. HTTP(s) Keyword and set a keyword you want to find
3. Set the URL to be monitored (this corresponds to the audience parameter in Authelia)
4. Configure Authentication as follows:
   • Method: OAuth2: Client Credentials
   • Authentication Method: Authorization Header
   • OAuth Token URL: https://auth.example.com/api/oidc/token
   • Client ID: uptime-kuma
   • Client Secret: insecure_secret
   • OAuth Scope: authelia.bearer.authz

See the following screenshot for an authentication example of the above: