The highest tagged major version is
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.
Thing SDK ¶
The Thing SDK allows things to connect to the ForgeRock Identity Platform either directly or via the Thing 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", 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 ¶
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 ¶
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 ¶
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) 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 Thing 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 Thing 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 Thing 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 PoP 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 Thing 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 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
Active returns true if the introspection indicates that the presented token is currently active.
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)
// 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)
// Logout will invalidate the thing's session with AM. It is good practice to log 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