iam

Identity and Access Management (IAM)

This repository contains the iam libraries, which is a collection of packages that control the authentication and authorization of users and services within Openlane. The repo is laid out at a high level containing:

• auth: primarily context interactions type definitions
• fgax: wrapper to interact with the OpenFGA go-sdk and client libraries
• entfga: an ent extension to create relationship tuples using ent Hooks
• providers: third party authentication flow(s); today github, google, oauth2 are supported with webauthn and oidc in-progress
• sessions: interfaces for managing user sessions with support for Redis as the session store
• tokens: tokenmanager which can create and validate tokens of various types, e.g. refresh tokens, access tokens, url tokens, etc.
• totp: second factor authentication library for generating unique, temporary passcodes

Token Signing (EdDSA)

The tokens package now issues and validates JWTs using Ed25519 (EdDSA). A few highlights:

• PEM files referenced in tokens.Config.Keys must contain Ed25519 key material encoded as PKCS#8 (PRIVATE KEY) with an accompanying PUBLIC KEY block.
• JWKS responses advertise alg=EdDSA/kty=OKP entries and will interoperate with lestrrat-go/jwx compatible consumers.
• The TokenManager exposes AddSigningKey/NewWithKey that accept generic crypto.Signer implementations; callers need to pass Ed25519 signers and handle returned errors. CurrentKeyID() surfaces the active key identifier even when it is not a ULID.
• The README within tokens documents usage in more detail, including signer helper functions.

Install

You can install iam by running the following command:

go get github.com/theopenlane/iam@latest

Usage

The goal of separating out the code that lives within this repo from the core repo is to make the authentication and authorization constructs re-usable across repositories / projects. Given that, core itself is a large consumer of the IAM repo and thus has many practical implementation examples. You can see instantiation of many of these libraries within serveropts and authmanager.

Providers

You can see practical examples with basic web interface setups within the core repository here

JWT Scopes

JWT claims can support per-object scopes. When integrating with core the scopes can be added in authmanager when creating the token pair.

func createClaimsWithOrgScopes(userID, orgID string) *tokens.Claims {
	return &tokens.Claims{
		RegisteredClaims: jwt.RegisteredClaims{
			Subject: userID,
		},
		UserID: userID,
		OrgID:  orgID,
		Scopes: tokens.PermissionScopes{
			Read:  []string{"programs", "controls"},
			Write: []string{"tasks"},
		},
	}
}

See tokens/_examples/claims_scopes.go for a minimal example

IAM/FGAX

This package includes helper functions used heavily in Openlane Core.

For example, you can easily check for Read access of an organization using

	// create client
	fgaClient, err := fgax.Client("https://fga-host.example.com")
	if err != nil {
		return false
	}

	// create access check
	req := fgax.AccessCheck{
		SubjectID:   "user-id",
		SubjectType: "user",
		ObjectID:    "organization-id",
	}

	allow, err := fgaClient.CheckOrgReadAccess(ctx, req)
	if err != nil {
		return false
	}

EntFGA

See the README for details

Contributing

Please read the contributing guide.