thing

package
v7.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2022 License: Apache-2.0 Imports: 12 Imported by: 7

Documentation

Overview

Package thing provides an SDK for devices and services (things) to interact with the ForgeRock Identity Platform. Use it to authenticate and authorize things and access their digital identities.

IoT SDK

The IoT SDK allows things to connect to the ForgeRock Identity Platform either directly or via the IoT Gateway. Things can perform tasks like register, authenticate, authorize and interact with their digital identity.

This is an example of using the SDK to register with the platform through Access Management's (AM) authentication trees. The platform must be configured with the provided parameters. 

// Initialise keys and certificates
var privateKey crypto.Signer = ...
keyID, _ := thing.JWKThumbprint(privateKey)
var certificate []*x509.Certificate = ...

// Connect directly to AM
amURL, _ := url.Parse("https://am.example.com:8443/am")

// Create a new thing and register it
myDevice, _ := builder.Thing().
    ConnectTo(amURL).
    InRealm("/all-the-things").
    WithTree("reg-auth-tree").
    AuthenticateThing("my-device", "/all-the-things", keyID, privateKey, nil).
    RegisterThing(certificate, nil).
    Create()

Authentication and Registration

AuthenticateThing and RegisterThing provides information for handling callbacks for the ForgeRock Authenticate/Register Thing tree nodes. These nodes use the JSON Web Token Proof of Possession (JWT PoP) specification (https://tools.ietf.org/html/rfc7800). They require a signed JWT containing Thing credentials and claims. Add custom claims to the registration JWT by providing a struct that can be serialized to JSON. 

RegisterThing(certificate, func() interface{} {
    return struct {
        SerialNumber string `json:"serial_number"`
        IPAddress    string `json:"ip_address"`
    }{
        SerialNumber: "LeCpmWjXpySAM22sxbUvCgGK",
        IPAddress:    "127.0.0.1",
    }
})

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DebugLogger 

func DebugLogger() *log.Logger

DebugLogger is the destination of all SDK debug information. The logger is muted by default. Redirect the debug output by assigning your own logger to this variable or setting the output writer, for example: 

thing.DebugLogger().SetOutput(os.Stdout)

func JWKThumbprint 

func JWKThumbprint(key crypto.Signer) (string, error)

JWKThumbprint calculates the base64url-encoded JWK Thumbprint value for the given key. The thumbprint can be used for identifying or selecting the key. See https://tools.ietf.org/html/rfc7638.

func SetDebugLogger 

func SetDebugLogger(logger *log.Logger)

SetDebugLogger will replace the default debug logger.

Types

type AccessTokenResponse 

type AccessTokenResponse struct {
	Content JSONContent
}

AccessTokenResponse contains the response received from AM after a successful access token request. The response format is specified in https://tools.ietf.org/html/rfc6749#section-4.1.4.

func (AccessTokenResponse) AccessToken 

func (a AccessTokenResponse) AccessToken() (string, error)

AccessToken returns the access token contained in an AccessTokenResponse.

func (AccessTokenResponse) ExpiresIn 

func (a AccessTokenResponse) ExpiresIn() (float64, error)

ExpiresIn returns the lifetime in seconds of the access token contained in an AccessTokenResponse.

func (AccessTokenResponse) RefreshToken added in v7.1.0 

func (a AccessTokenResponse) RefreshToken() (string, error)

RefreshToken returns the refresh token contained in an AccessTokenResponse.

func (AccessTokenResponse) Scope 

func (a AccessTokenResponse) Scope() ([]string, error)

Scope returns the scopes of the access token contained in an AccessTokenResponse.

type AttributesResponse 

type AttributesResponse struct {
	Content JSONContent
}

AttributesResponse contains the response received from AM after a successful request for thing attributes. The name of the attribute is the same as the LDAP identity attribute name. The response will contain the thing ID and may have multiple values for a single attribute, for example: 

{
    "_id": "my-device",
    "foo": ["a", "b", "c"]
    "bar": ["1"]
}

func (AttributesResponse) GetFirst 

func (a AttributesResponse) GetFirst(key string) (string, error)

GetFirst reads the first value for the specified attribute from the AttributesResponse.

func (AttributesResponse) ID 

func (a AttributesResponse) ID() (string, error)

ID returns the thing's ID contained in an AttributesResponse.

type Builder 

type Builder interface {

	// ConnectTo the server at the given URL.
	// Supports http(s) for connecting to AM and coap(s) for connecting to the IoT Gateway.
	// When connecting to AM, the URL should be either the top level realm in AM or the DNS alias of a sub realm.
	ConnectTo(url *url.URL) Builder

	// InRealm specifies the path to the AM realm in which the thing should authenticate and operate in.
	// This can be a realm alias or the fully qualified realm path, for example:
	//  - root realm: "/"
	//  - a sub-realm of root called "alfheim": "/alfheim"
	//  - a sub-realm of alfheim called "svartalfheim": "/alfheim/svartalfheim"
	//
	// The realm should not be set if a DNS alias is being used to connect to AM.
	// The realm is not required if the thing is connecting to the IoT Gateway. If provided it will be ignored.
	InRealm(realm string) Builder

	// WithTree sets the name of the AM authentication tree that will be used to register and authenticate the thing.
	// The tree is not required if the thing is connecting to the IoT Gateway. If provided it will be ignored.
	WithTree(tree string) Builder

	// AsService registers the thing as a service. By default, a thing is registered as a device.
	AsService() Builder

	// AuthenticateThing with the ForgeRock Authenticate Thing tree node. This node uses JWT authentication and requires
	// a JWT signed with the key that was registered for the thing. The JWT must contain the key ID provided for the
	// registered key. In addition, the JWT may include custom claims about the thing. The claims will be available for
	// processing by the proceeding nodes in the tree.
	AuthenticateThing(thingID string, audience string, keyID string, key crypto.Signer, claims func() interface{}) Builder

	// RegisterThing with the ForgeRock Register Thing tree node. This node uses JWT PoP and requires a signed JWT
	// containing the thing's public key and key ID, along with a CA signed certificate that contains the same public
	// key. This method must be used along with the AuthenticateThing method as they share the same thing ID,
	// key and key ID. They do not share claims however. The JWT may include custom claims about the thing, which will
	// be added to the thing's identity on successful registration.
	RegisterThing(certificates []*x509.Certificate, claims func() interface{}) Builder

	// HandleCallbacksWith the supplied callback handlers when the thing is authenticated. The provided handlers must
	// match those configured in the AM authentication tree.
	HandleCallbacksWith(handlers ...callback.Handler) Builder

	// TimeoutRequestAfter sets the timeout on the communications between the Thing and AM or the IoT Gateway.
	TimeoutRequestAfter(time.Duration) Builder

	// Create a Thing instance and make an authentication request to AM. The callback handlers and information provided
	// in the AuthenticateThing and RegisterThing methods will be used to satisfy the callbacks received from the AM
	// authentication process.
	Create() (Thing, error)
}

Builder interface provides methods to setup and initialise a Thing.

type DeviceAuthorizationResponse added in v7.1.0 

type DeviceAuthorizationResponse struct {
	DeviceCode              string  `json:"device_code"`
	UserCode                string  `json:"user_code"`
	VerificationURI         string  `json:"verification_uri"`
	VerificationURIComplete string  `json:"verification_uri_complete,omitempty"`
	ExpiresIn               float64 `json:"expires_in"`
	Interval                float64 `json:"interval,omitempty"`
}

DeviceAuthorizationResponse contains the response received from AM after a successful device authorization request. The response format is specified in https://tools.ietf.org/html/rfc8628#section-3.2.

type IntrospectionResponse 

type IntrospectionResponse struct {
	Content JSONContent
}

IntrospectionResponse contains the introspection of an OAuth 2.0 token. The response format is specified in https://tools.ietf.org/html/rfc7662#section-2.2.

func (IntrospectionResponse) Active 

func (i IntrospectionResponse) Active() (bool, error)

Active returns true if the introspection indicates that the presented token is currently active.

func (IntrospectionResponse) Scope added in v7.1.0 

func (i IntrospectionResponse) Scope() ([]string, error)

Scope returns the scopes of the token represented by the IntrospectionResponse.

type JSONContent 

type JSONContent map[string]interface{}

JSONContent holds dynamic JSON data

func (JSONContent) GetBool 

func (c JSONContent) GetBool(key string) (bool, error)

GetBool returns the boolean value associated with the key in the JSON object

func (JSONContent) GetNumber 

func (c JSONContent) GetNumber(key string) (float64, error)

GetNumber returns the number value associated with the key in the JSON object

func (JSONContent) GetString 

func (c JSONContent) GetString(key string) (string, error)

GetString returns the string value associated with the key in the JSON object

func (JSONContent) GetStringArray 

func (c JSONContent) GetStringArray(key string) ([]string, error)

GetStringArray returns all the string values held in the array associated with the key in the JSON object

type Thing 

type Thing interface {

	// RequestAccessToken requests an OAuth 2.0 access token for a thing. The provided scopes will be included in the token
	// if they are configured in the thing's associated OAuth 2.0 Client in AM. If no scopes are provided then the token
	// will include the default scopes configured in the OAuth 2.0 Client.
	RequestAccessToken(scopes ...string) (response AccessTokenResponse, err error)

	// RefreshAccessToken refreshes an OAuth 2.0 access token using the given refresh token. The new access
	// token will have the same scope as the original token by default. Provide a subset of the original scopes to have
	// a reduced set of scopes in the new access token. The thing requesting the refresh must be the same thing that
	// requested the original access token.
	RefreshAccessToken(refreshToken string, scopes ...string) (response AccessTokenResponse, err error)

	// IntrospectAccessToken introspects an OAuth 2.0 access token for a thing as defined by rfc7662.
	// Supports only client-based OAuth 2.0 tokens signed with an asymmetric key.
	IntrospectAccessToken(token string) (introspection IntrospectionResponse, err error)

	// RequestAttributes requests the attributes with the specified names associated with the thing's identity.
	// If no names are specified then all the allowed attributes will be returned.
	RequestAttributes(names ...string) (response AttributesResponse, err error)

	// RequestUserCode makes the device authorization request as defined by the OAuth 2.0 Device Authorization Grant
	// specification (rfc8628). The device authorization response can be used to request a user access token with the
	// RequestUserToken method. The provided scopes will be included in the token if they are configured in the thing's
	// associated OAuth 2.0 Client in AM. If no scopes are provided then the token will include the default scopes
	// configured in the OAuth 2.0 Client.
	RequestUserCode(scopes ...string) (response DeviceAuthorizationResponse, err error)

	// RequestUserToken makes the device access token request as defined by the OAuth 2.0 Device Authorization Grant
	// specification (rfc8628). The authorizationResponse can be retrieved by calling RequestUserCode. This method will
	// block until the user authorizes the request or the device code expires.
	RequestUserToken(authorizationResponse DeviceAuthorizationResponse) (response AccessTokenResponse, err error)

	// Logout will invalidate the thing's session with AM. It is good practice logging out if the thing will not make
	// new requests for a prolonged period. Once logged out the thing will automatically create a new session when a
	// new request is made.
	Logout() error
}

Thing represents a device or a service with a digital identity in the ForgeRock Identity Platform.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.