OAuth2.0

Server Smalltalk Guide : OAuth2.0 and OpenID Connect : OAuth2.0

OAuth2.0

Description

This is a client library for authenticating with a remote service using the OAuth2.0 protocol on behalf of a user, and making authorized HTTP(s) requests with the user's OAuth2.0 credentials and/or acquire user details for authentication and single sign-on functionality according to the OpenID Connect protocol. See the SstOIDCApp.

How it works.

The OAuth2.0 protocol defines several possible methods to obtain a user's authorization for use of a remote (HTTP) service. These different methods are called 'grant types' and a remote service is free to choose which grant types it supports and which not. Grant types are sometimes referred to as 'flows', particularly when used in the context of the OpenID Connect protocol.

Most remote services that implement OAuth2.0 authorization will also require a client application to be registered with the service before it can try to authorize a user. Such client applications are referred to as "confidential clients". When registering a confidential client, the developer of the client application receives a client id and client secret. These credentials identify the client application with the remote service.

When the client has successfully obtained authorization on behalf of a user, using the protocol defined by a specific grant type, it receives an "access token" from the service's authorization server. The client can then use this token to access the resources of the remote service (e.g. an API) for which the authenticated user has authorized its access.

To this end, the result of the authorization process is a <SstOAuth2HttpClient> which is a subclass of <SstHttpClient>. It will automatically use the obtained access token in http requests and, when possible, refresh the access token when it has expired.

In the case of OpenID Connect, an id token is also returned together with the access token. This id token is JSON Web Token (JWT) that supplies information about the end user in the form of claims.

The obtained OAuth2.0 and OpenID Connect credentials (including the access token) can be serialized to JSON and used to create a new instance of the <SstOAuth2HttpClient> . This allows application developers to store the obtained credentials for later use.

Supported grant types

OAuth2.0 defines several grant types but new and custom grant types can be defined as well. This client has built-in support for the following grant types:

Authorization Code with PKCE (<SstOAuth2AuthorizationCodeGrant>)
Client Credentials (<SstOAuth2ClientCredentialsGrant>)
Resource Owner Password Credentials (<SstOAuth2ResourceOwnerPasswordGrant>)
JWT Bearer (<SstOAuth2JWTBearerGrant>)

We do not support the Implicit grant type but we do make it possible to extend the framework for new and custom grant types.

The most commonly-used grant type (or flow) is the Authorization Code grant type, which requires a user to authenticate with the remote service via a web browser. This is the default for almost all web applications. The Implicit grant serves less secure applications such as Mobile Applications or Single-Page Applications, while the Client Credentials grant is mostly applicable to backend (headless) applications. However, for headless applications, an access token obtained via the Authorization Code grant can be accompanied with a refresh token that allows to refresh the access token without user interaction. Finally, the Resource Owner Password Credentials grant is applicable when there is a high degree of trust between the resource owner and the client application.

Code flow

The following code snippet illustrates how to use the library with the Authorization Code grant. It is important to note that the redirection of the user to the authorization server in this code snippet is using a fictious method. We refer to the complete examples included in the feature "VA: Server Smalltalk (SST) - OAuth2/OIDC Examples" for full implementations using both an external web browser as well as a WebView2 window in a Seaside and a desktop UI application.

"Create a grant object and use it to create the url to which the user needs to be redirected to authenticate."

grant := SstOAuth2AuthorizationCodeGrant

    newWithClientId: '12345679' 

    authorizationBaseUrl: 'https://oauth2-service.com/authorize' sstAsUrl 

    tokenUrl: 'https://oauth2-service.com/accesstoken' sstAsUrl.

grant 

    clientSecret: 'abcdefghk1125-02';

    scope: 'api-access'.

authorizationUrl := grant 

    authorizationUrlWithRedirectTo: 'https://myapplication.com/authorize-callback' sstAsUrl 

    state: 'random state string'.

"Fictitious method which implements the user redirection to the authorization url and receives the result."

self

    redirectTo: authorizationUrl

    handleCallbackAt: 'https://myapplication.com/authorize-callback' sstAsUrl

    with: [ :authorizeResultRequest | 

        httpClientWithOAuth2 := grant createClientFromAuthorizationResponseData: authorizeResultRequest queryFields ].

"Use the http client to access the protected resource."

httpClientWithOAuth2 get: 'https://api-service.com/protectedinfo'

Class Methods

None

Instance Methods

None

Last modified date: 01/15/2026