Documentation
¶
Overview ¶
Package microsoft provides shared Microsoft identity platform, Graph, and Azure helpers for Microsoft and Azure integration definitions. It is not an integration definition itself
Index ¶
- Constants
- Variables
- func AdminConsentFlow[T any](cfg AppConfig, newCredential func(tenantID string) T) types.AuthFlow[T]
- func AdminConsentURL(tenant string) string
- func AuthorizeURL(tenant string) string
- func NewTokenCredential(cfg AppConfig, tenantID string) (azcore.TokenCredential, error)
- func TokenClaim(token, name string) string
- func TokenClaims(token string) (jwt.MapClaims, error)
- func TokenURL(tenant string) string
- type ARMClient
- func (c *ARMClient) DeleteDelegation(ctx context.Context, assignmentID string) error
- func (c *ARMClient) ListDelegations(ctx context.Context, subscriptionID, managedByTenantID string) ([]Delegation, error)
- func (c *ARMClient) ListSubscriptionIDs(ctx context.Context, tenantID string) ([]string, error)
- func (c *ARMClient) QueryResourceGraph(ctx context.Context, query string, subscriptionIDs []string) ([]json.RawMessage, error)
- type AppConfig
- func (c AppConfig) ARMClientOptions() *arm.ClientOptions
- func (c AppConfig) NewDelegatedGraphClient(ctx context.Context, tenant string, token *oauth2.Token) (*msgraphsdk.GraphServiceClient, oauth2.TokenSource, error)
- func (c AppConfig) NewGraphClient(cred azcore.TokenCredential) (*msgraphsdk.GraphServiceClient, error)
- type Delegation
- type LighthouseConfig
- type LighthouseOffer
- type OAuthTokenCredential
Constants ¶
const ( // SecurityReaderRoleID is the Azure built-in Security Reader role definition ID SecurityReaderRoleID = "39bc4728-0917-49c7-9d2c-d95423bc2eb4" // RegistrationAssignmentDeleteRoleID is the Azure built-in role that lets the managing tenant read and remove its own Lighthouse delegations RegistrationAssignmentDeleteRoleID = "91c1777a-f3dc-4fae-b103-61d183457e46" )
const ( // CommonTenant is the tenant segment that accepts both work/school and personal Microsoft accounts CommonTenant = "common" // OrganizationsTenant is the tenant segment that accepts any work/school account OrganizationsTenant = "organizations" )
const GraphScope = "https://graph.microsoft.com/.default"
GraphScope is the default scope used for Microsoft Graph client credentials requests
Variables ¶
var ( // ErrTenantIDRequired indicates a token credential was requested without a tenant ID ErrTenantIDRequired = errors.New("microsoft: tenant id required") // ErrTokenCredentialBuild indicates the client secret token credential could not be constructed ErrTokenCredentialBuild = errors.New("microsoft: token credential build failed") // ErrSubscriptionListFailed indicates the ARM subscriptions listing request failed ErrSubscriptionListFailed = errors.New("microsoft: subscription list failed") // ErrRegistrationAssignmentListFailed indicates the Lighthouse registration assignments listing request failed ErrRegistrationAssignmentListFailed = errors.New("microsoft: registration assignment list failed") // ErrRegistrationAssignmentDeleteFailed indicates a Lighthouse registration assignment could not be removed ErrRegistrationAssignmentDeleteFailed = errors.New("microsoft: registration assignment delete failed") // ErrLighthouseTemplateBuild indicates the Lighthouse ARM template could not be encoded ErrLighthouseTemplateBuild = errors.New("microsoft: lighthouse template build failed") // ErrResourceGraphQueryFailed indicates an Azure Resource Graph query failed ErrResourceGraphQueryFailed = errors.New("microsoft: resource graph query failed") // ErrTenantIDNotFound indicates the tenant ID was not returned on the admin consent callback ErrTenantIDNotFound = errors.New("microsoft: tenant id not found in admin consent callback") // ErrCredentialEncode indicates the credential could not be serialized ErrCredentialEncode = errors.New("microsoft: credential encode failed") // ErrConsentStateGeneration indicates the CSRF state could not be generated for the admin consent flow ErrConsentStateGeneration = errors.New("microsoft: admin consent state generation failed") // ErrConsentStateInvalid indicates the stored admin consent start state could not be decoded ErrConsentStateInvalid = errors.New("microsoft: admin consent state invalid") // ErrConsentStateMismatch indicates the callback state does not match the stored CSRF state ErrConsentStateMismatch = errors.New("microsoft: admin consent state mismatch") // ErrConsentDenied indicates the admin denied or cancelled the consent request ErrConsentDenied = errors.New("microsoft: admin consent denied") )
Functions ¶
func AdminConsentFlow ¶
func AdminConsentFlow[T any](cfg AppConfig, newCredential func(tenantID string) T) types.AuthFlow[T]
AdminConsentFlow builds an auth flow that uses the Azure admin consent endpoint which grants application permissions so the client credentials flow can access the tenant
func AdminConsentURL ¶
AdminConsentURL returns the v2.0 admin consent endpoint for a tenant
func AuthorizeURL ¶
AuthorizeURL returns the OAuth2 v2.0 authorize endpoint for a tenant
func NewTokenCredential ¶
func NewTokenCredential(cfg AppConfig, tenantID string) (azcore.TokenCredential, error)
NewTokenCredential builds a client credentials token credential for the app in one consented tenant
func TokenClaim ¶
TokenClaim returns a string claim from a Microsoft-issued JWT without verifying it, empty when absent
func TokenClaims ¶
TokenClaims returns the claims of a Microsoft-issued JWT without verifying it
Types ¶
type ARMClient ¶
type ARMClient struct {
// contains filtered or unexported fields
}
ARMClient calls Azure Resource Manager APIs for one tenant credential
func NewARMClient ¶
func NewARMClient(cfg AppConfig, cred azcore.TokenCredential) (*ARMClient, error)
NewARMClient builds an ARM client for the credential, honoring the app config's endpoint overrides
func (*ARMClient) DeleteDelegation ¶
DeleteDelegation removes a Lighthouse registration assignment, which requires the Registration Assignment Delete role
func (*ARMClient) ListDelegations ¶
func (c *ARMClient) ListDelegations(ctx context.Context, subscriptionID, managedByTenantID string) ([]Delegation, error)
ListDelegations returns the subscription's Lighthouse delegations to managedByTenantID
func (*ARMClient) ListSubscriptionIDs ¶
ListSubscriptionIDs returns every usable subscription owned by tenantID that the credential has an RBAC role assignment on
func (*ARMClient) QueryResourceGraph ¶
func (c *ARMClient) QueryResourceGraph(ctx context.Context, query string, subscriptionIDs []string) ([]json.RawMessage, error)
QueryResourceGraph runs a KQL query against Azure Resource Graph and returns every result row
type AppConfig ¶
type AppConfig struct {
// ApplicationID is the Application (client) ID from the Azure app registration Overview page, used as the OAuth client ID and in the well-known configuration for domain validation
ApplicationID string `json:"applicationid" koanf:"applicationid"`
// ClientSecret is the client secret Value (not the Secret ID) from the Azure app registration
ClientSecret string `json:"clientsecret" koanf:"clientsecret" sensitive:"true"`
// RedirectURL is the OAuth callback URL registered with the Azure application
RedirectURL string `json:"redirecturl" koanf:"redirecturl" default:"https://api.theopenlane.io/v1/integrations/auth/callback"`
// DefaultTenant pins the admin consent flow to a specific tenant ID or domain (e.g. for local dev/testing)
// when empty the generic /organizations endpoint is used
DefaultTenant string `json:"defaulttenant" koanf:"defaulttenant"`
// contains filtered or unexported fields
}
AppConfig holds operator-level credentials for one multi-tenant Azure application registration
func (AppConfig) ARMClientOptions ¶
func (c AppConfig) ARMClientOptions() *arm.ClientOptions
ARMClientOptions returns the ARM client options for the configured endpoints, nil for the public cloud
func (AppConfig) NewDelegatedGraphClient ¶
func (c AppConfig) NewDelegatedGraphClient(ctx context.Context, tenant string, token *oauth2.Token) (*msgraphsdk.GraphServiceClient, oauth2.TokenSource, error)
NewDelegatedGraphClient builds a Graph client from stored delegated OAuth material, returning the refreshing token source for plain HTTP calls
func (AppConfig) NewGraphClient ¶
func (c AppConfig) NewGraphClient(cred azcore.TokenCredential) (*msgraphsdk.GraphServiceClient, error)
NewGraphClient builds a Microsoft Graph service client for the configured endpoints
type Delegation ¶
type Delegation struct {
// AssignmentID is the fully qualified ARM path of the registration assignment
AssignmentID string
// OfferName is the registration definition name
OfferName string
}
Delegation is one Lighthouse registration assignment on a subscription
func FindDelegation ¶
func FindDelegation(delegations []Delegation, name string) (Delegation, bool)
FindDelegation returns the delegation whose offer name matches name, ignoring case
type LighthouseConfig ¶
type LighthouseConfig struct {
// ManagingTenantID is the Openlane tenant that customer subscriptions are delegated to
ManagingTenantID string `json:"managingtenantid" koanf:"managingtenantid"`
// PrincipalID is the object ID of the Openlane app's service principal in the managing tenant
PrincipalID string `json:"principalid" koanf:"principalid"`
}
LighthouseConfig holds the managing tenant settings customers delegate Azure subscriptions to through Azure Lighthouse
func (LighthouseConfig) Template ¶
func (c LighthouseConfig) Template(offer LighthouseOffer) (string, error)
Template returns the subscription-scope ARM template that delegates a subscription to the managing tenant principal for the offer
type LighthouseOffer ¶
type LighthouseOffer struct {
// NamePrefix starts the offer name shown to the customer; the connection code completes it
NamePrefix string
// Description is the offer description shown to the customer
Description string
// PrincipalDisplayName labels the managing tenant principal in the customer's Service providers page
PrincipalDisplayName string
// RoleDefinitionIDs are the built-in roles granted to the principal on the delegated subscription
RoleDefinitionIDs []string
}
LighthouseOffer describes the delegation a Lighthouse template grants the managing tenant principal
func (LighthouseOffer) OfferName ¶
func (o LighthouseOffer) OfferName(code string) string
OfferName returns the offer name a template deployment with the connection code registers
type OAuthTokenCredential ¶
type OAuthTokenCredential struct {
// contains filtered or unexported fields
}
OAuthTokenCredential wraps an oauth2.TokenSource as an azcore.TokenCredential so that the kiota authentication provider can obtain automatically-refreshed access tokens
func NewOAuthTokenCredential ¶
func NewOAuthTokenCredential(ts oauth2.TokenSource) *OAuthTokenCredential
NewOAuthTokenCredential wraps a token source as an azcore.TokenCredential
func (*OAuthTokenCredential) GetToken ¶
func (c *OAuthTokenCredential) GetToken(_ context.Context, _ policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken obtains the current (or refreshed) access token from the underlying oauth2.TokenSource