Set up OAuth

View as Markdown

Experimental: OAuth support is currently experimental. OAuth credentials are not encrypted; this feature will be extended in the future to include credential encryption. Use with caution until then.

For applications that need OAuth authentication to access an account's information, Krenalis provides an OAuth implementation for connectors. The connector only needs to provide some information during registration and implement a method to retrieve the application's account that was connected through authentication.

After that, you just need to use the HTTP client provided to the constructor to make HTTP requests to the application. Krenalis will automatically handle adding authentication information and keep it updated.

The following example shows how a connector for a generic application (called "Acmify" in this example) provides some OAuth-specific information during registration:

connectors.RegisterApplication(connectors.ApplicationSpec{
    OAuth:   connectors.OAuth{
        AuthURL:           "https://acmify.example.com/oauth2/authorize",
        TokenURL:          "https://api.acmify.example.com/oauth2/token",
        SourceScopes:      []string{
                "profile.read",
                "records.read",
        },
        DestinationScopes: []string{
                "profile.read",
                "records.read",
                "records.write",
        },
        Disallow127_0_0_1: true,
    },
    // other fields are omitted.
}, New)

The connectors.OAuth type contains this information:

  • AuthURL: authorization endpoint, the URL where users are redirected to grant consent.
  • TokenURL: token endpoint, the URL used to retrieve the access token, refresh token, and token lifetime.
  • SourceScopes: required scopes when used as a source. Leave empty if there are no source scopes.
  • DestinationScopes: required scopes when used as a destination. Leave empty if there are no destination scopes.
  • ExpiresIn: lifetime of the access token in seconds. If the value is zero or negative, the lifetime is provided by the TokenURL endpoint.
  • Disallow127_0_0_1: if true, the redirect URL cannot use 127.0.0.1 as its host.
  • DisallowLocalhost: if true, the redirect URL cannot use localhost as its host.

If AuthURL and TokenURL contain query string arguments, they will be preserved.

For endpoint groups that require OAuth for authentication, set the RequireOAuth field to true. The AuthURL and TokenURL endpoints are not affected.

OAuthAccount method

OAuthAccount(ctx context.Context) (string, error)

The OAuthAccount method is called by Krenalis after a successful OAuth authentication to obtain the application's account associated with the given authorization. The connector uses the HTTP client provided to the constructor to call the API to obtain the account. The account must be a non-empty UTF-8 encoded string.

ClientSecret and AccessToken

If you need the client secret or the access token, they can be obtained from the ClientSecret and AccessToken methods of the HTTP client.