gocloak

Keycloak's permission system uses tickets and grants to manage resource access:

1. Creating a Ticket: Use CreatePermissionTicketParams specifying ResourceID, ResourceScopes, and optional Claims.
2. Permission Ticket Response: The server returns a PermissionTicketResponseRepresentation containing the Ticket string.
3. Permission Ticket Content: The PermissionTicketRepresentation (which embeds jwt.RegisteredClaims) contains the AZP, Claims, and a list of PermissionTicketPermissionRepresentation (mapping scopes to resource IDs).
4. Granting Permission: Use PermissionGrantParams to grant a specific ResourceID and ScopeName to a RequesterID using a TicketID.

Organizations in Keycloak use MembershipType to define how members relate to the organization:

• MembershipTypeManaged: The member cannot exist without the organization.
• MembershipTypeUnmanaged: The member can exist independently of the organization.

Use MemberRepresentation to represent an organization member, which embeds the standard User type and includes the MembershipType.

// MembershipType constants
const (
    MembershipTypeManaged   MembershipType = "MANAGED"
    MembershipTypeUnmanaged MembershipType = "UNMANAGED"
)

type MemberRepresentation struct {
    User
    MembershipType *MembershipType `json:"membershipType,omitempty"`
}

The project provides a docker-compose.yml file to set up a local development environment consisting of Keycloak and MailHog.

Keycloak is configured in development mode (start-dev) with specific features enabled and an automatic realm import. MailHog is included to handle email testing.

To run the environment, use the standard Docker Compose command:

When initializing NewClient, you can pass several functional options to override default configurations:

• SetServerVersion(version string): Sets the Keycloak version to bypass the initial serverinfo call.
• SetLegacyWildFlySupport(): Adjusts realm URL paths for older WildFly-based Keycloak installations.
• SetAuthRealms(url string): Overrides the default auth realm path.
• SetAuthAdminRealms(url string): Overrides the default admin realm path.
• SetTokenEndpoint(url string): Overrides the OIDC token endpoint.
• SetCertCacheInvalidationTime(duration time.Duration): Sets how long certificates are kept in the local cache.

When using the provided docker-compose.yml, Keycloak is configured with the following environment variables:

• KEYCLOAK_ADMIN: The initial admin username (set to admin).
• KEYCLOAK_ADMIN_PASSWORD: The initial admin password (set to secret).
• KC_HEALTH_ENABLED: Enables the health endpoint (set to "true").

Keycloak is also configured to import a realm from a local file via the volume mapping: ./testdata/gocloak-realm.json:/opt/keycloak/data/import/gocloak-realm.json.

The UserProfileConfig defines how user attributes are managed. It includes UserProfileAttribute definitions which specify:

• Validations and Annotations (maps)
• Required roles and scopes via UserProfileAttributeRequired
• Permissions for viewing and editing via UserProfileAttributePermissions
• Selector scopes via UserProfileAttributeSelector

Unmanaged attributes are governed by UnmanagedAttributePolicy:

• UnmanagedAttributePolicyEnabled: Unmanaged attributes can be used.
• UnmanagedAttributePolicyAdminView: Unmanaged attributes are disabled and only visible to admins.
• UnmanagedAttributePolicyAdminEdit: Unmanaged attributes can be viewed and edited only by admins.

Protocol mappers allow you to customize the tokens issued by a client. Use these methods to manage them within a client scope:

• CreateClientProtocolMapper(ctx, token, realm, idOfClient, mapper): Creates a new protocol mapper. Returns the new mapper's ID.
• UpdateClientProtocolMapper(ctx, token, realm, idOfClient, mapperID, mapper): Updates an existing mapper.
• DeleteClientProtocolMapper(ctx, token, realm, idOfClient, mapperID): Deletes a mapper.
• GetClientScopeProtocolMappers(ctx, token, realm, scopeID): Lists all mappers for a specific client scope.
• GetClientScopeProtocolMapper(ctx, token, realm, scopeID, protocolMapperID): Retrieves a specific mapper by ID.
• DeleteClientScopeProtocolMapper(ctx, token, realm, scopeID, protocolMapperID): Deletes a mapper from a client scope.

You can revoke an access or refresh token using the RevokeToken method. This requires client credentials (ID and Secret) and uses Basic Authentication.

err := g.RevokeToken(ctx, realm, clientID, clientSecret, refreshToken)