Documentation

Codeberg extends OAuth2Provider
in package
implements CSRFToken, PKCE, TokenRefresh, UserInfo uses PKCETrait

Codeberg OAuth2

Tags
link
https://forgejo.org/docs/latest/user/oauth2-provider/
link
https://forgejo.org/docs/latest/user/token-scope/
link
https://codeberg.org/api/swagger

Table of Contents

Interfaces

CSRFToken
Specifies the methods required for the OAuth2 CSRF token validation ("state parameter")
PKCE
Specifies the methods required for the OAuth2 Proof Key for Code Exchange (PKCE)
TokenRefresh
Indicates whether the provider is capable of the OAuth2 token refresh.
UserInfo
Indicates whether the service can provide information about the currently authenticated user, usually via a "/me", "/user" or "/tokeninfo" endpoint.

Constants

DEFAULT_SCOPES  = [self::SCOPE_REPOSITORY_READ, self::SCOPE_USER_READ]
IDENTIFIER  = 'CODEBERG'
SCOPE_ACTIVITYPUB  = 'activitypub'
SCOPE_ACTIVITYPUB_READ  = 'read:activitypub'
SCOPE_ACTIVITYPUB_WRITE  = 'write:activitypub'
SCOPE_ADMIN  = 'admin'
SCOPE_ADMIN_READ  = 'read:admin'
SCOPE_ADMIN_WRITE  = 'write:admin'
SCOPE_ISSUE  = 'issue'
SCOPE_ISSUE_READ  = 'read:issue'
SCOPE_ISSUE_WRITE  = 'write:issue'
SCOPE_MISC  = 'misc'
SCOPE_MISC_READ  = 'read:misc'
SCOPE_MISC_WRITE  = 'write:misc'
SCOPE_NOTIFICATION  = 'notification'
SCOPE_NOTIFICATION_READ  = 'read:notification'
SCOPE_NOTIFICATION_WRITE  = 'write:notification'
SCOPE_ORGANIZATION  = 'organization'
SCOPE_ORGANIZATION_READ  = 'read:organization'
SCOPE_ORGANIZATION_WRITE  = 'write:organization'
SCOPE_PACKAGE  = 'package'
SCOPE_PACKAGE_READ  = 'read:package'
SCOPE_PACKAGE_WRITE  = 'write:package'
SCOPE_REPOSITORY  = 'repository'
SCOPE_REPOSITORY_READ  = 'read:repository'
SCOPE_REPOSITORY_WRITE  = 'write:repository'
SCOPE_USER  = 'user'
SCOPE_USER_READ  = 'read:user'
SCOPE_USER_WRITE  = 'write:user'

Properties

$accessTokenURL  : string
$apiDocs  : string|null
$apiURL  : string
$applicationURL  : string|null
$authorizationURL  : string
$clientCredentialsTokenURL  : string|null
An optional client credentials token endpoint in case the provider supports ClientCredentials.
$http  : ClientInterface
The PSR-18 HTTP client
$logger  : LoggerInterface
A PSR-3 logger
$name  : string
The name of the provider/class
$options  : OAuthOptions|SettingsContainerInterface
The options instance
$parAuthorizationURL  : string
An optional PAR (Pushed Authorization Request) endpoint URL
$refreshTokenURL  : string|null
An optional refresh token endpoint in case the provider supports TokenRefresh.
$requestFactory  : RequestFactoryInterface
A PSR-17 request factory
$revokeURL  : string
An optional URL for application side token revocation
$storage  : OAuthStorageInterface
A storage instance
$streamFactory  : StreamFactoryInterface
A PSR-17 stream factory
$uriFactory  : UriFactoryInterface
A PSR-17 URI factory
$userRevokeURL  : string|null

Methods

__construct()  : mixed
OAuthProvider constructor.
checkState()  : void
implements CSRFToken::checkState()
generateChallenge()  : string
implements PKCE::generateChallenge()
generateVerifier()  : string
implements PKCE::generateVerifier()
getAccessToken()  : AccessToken
Obtains an OAuth2 access token with the given $code, verifies the $state if the provider implements the CSRFToken interface, and returns an AccessToken object
getAccessTokenFromStorage()  : AccessToken
Gets an access token from the current OAuthStorageInterface (shorthand/convenience)
getApiDocURL()  : string|null
Returns the link to the provider's API docs, or null if the value is not set
getApplicationURL()  : string|null
Returns the link to the provider's credential registration/application page, or null if the value is not set
getAuthorizationURL()  : UriInterface
Prepares the URL with optional $params which redirects to the provider's authorization prompt and returns a PSR-7 UriInterface with all necessary parameters set.
getName()  : string
Returns the name of the provider/class
getRequestAuthorization()  : RequestInterface
Authorizes the $request with the credentials from the given $token and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set
getStorage()  : OAuthStorageInterface
Returns the current OAuthStorageInterface
getUserRevokeURL()  : string|null
Returns the link to the page where a user can revoke access tokens, or null if the value is not set
InvalidateAccessToken()  : bool
implements TokenInvalidate
me()  : AuthenticatedUser
Returns information about the currently authenticated user (usually a /me or /user endpoint).
refreshAccessToken()  : AccessToken
implements TokenRefresh::refreshAccessToken()
request()  : ResponseInterface
Prepares an API request to $path with the given parameters, gets authorization, fires the request and returns a PSR-7 ResponseInterface with the corresponding API response
sendRequest()  : ResponseInterface
setCodeChallenge()  : array<string, string>
implements PKCE::setCodeChallenge()
setCodeVerifier()  : array<string, string>
implements PKCE::setCodeVerifier()
setLogger()  : static
Sets an optional PSR-3 LoggerInterface
setRequestFactory()  : static
Sets an optional PSR-17 RequestFactoryInterface
setState()  : array<string, string>
implements CSRFToken::setState()
setStorage()  : static
Sets an optional OAuthStorageInterface
setStreamFactory()  : static
Sets an optional PSR-17 StreamFactoryInterface
setUriFactory()  : static
Sets an optional PSR-17 UriFactoryInterface
storeAccessToken()  : static
Sets an access token in the current OAuthStorageInterface (shorthand/convenience)
addBasicAuthHeader()  : RequestInterface
Adds an "Authorization: Basic <base64(key:secret)>" header to the given request
cleanBodyParams()  : array<string, string>
Cleans an array of body parameters
cleanQueryParams()  : array<string, string>
Cleans an array of query parameters
construct()  : void
A replacement constructor that you can call in extended classes, so that you don't have to implement the monstrous original `__construct()`
createAccessToken()  : AccessToken
Creates an access token with the provider set to $this->name
getAccessTokenRequestBodyParams()  : array<string, string>
prepares the request body parameters for the access token request
getAuthorizationURLRequestParams()  : array<string, string>
prepares the query parameters for the auth URL
getMeResponseData()  : array<int|string, mixed>
fetches the provider's "me" endpoint and returns the JSON data as an array
getRefreshAccessTokenRequestBodyParams()  : array<string, string|null>
prepares the request body parameters for the token refresh
getRequestHeaders()  : array<string, string>
Prepare request headers
getRequestTarget()  : string
Determine the request target from the given URI (path segment or URL) with respect to $apiURL, anything except host and path will be ignored, scheme will always be set to "https".
getRequestURL()  : string
Prepares the request URL
getTokenResponseData()  : array<string, string|mixed>
extracts the data from the access token response and returns an array with the key->value pairs contained
handleMeResponseError()  : void
handles errors for the `me()` endpoints - one horrible block of code to catch them all
nonce()  : string
returns a 32 byte random string (in hexadecimal representation) for use as a nonce
parseTokenResponse()  : AccessToken
Parses the response from a request to the token endpoint
sendAccessTokenRequest()  : ResponseInterface
sends a request to the access/refresh token endpoint $url with the given $body as form data
sendMeRequest()  : ResponseInterface
prepares and sends the request to the provider's "me" endpoint and returns a ResponseInterface
setRequestBody()  : RequestInterface
Prepares the request body and sets it in the given RequestInterface, along with a Content-Length header

Constants

DEFAULT_SCOPES

public mixed DEFAULT_SCOPES = [self::SCOPE_REPOSITORY_READ, self::SCOPE_USER_READ]

IDENTIFIER

public mixed IDENTIFIER = 'CODEBERG'

SCOPE_ACTIVITYPUB

public mixed SCOPE_ACTIVITYPUB = 'activitypub'

SCOPE_ACTIVITYPUB_READ

public mixed SCOPE_ACTIVITYPUB_READ = 'read:activitypub'

SCOPE_ACTIVITYPUB_WRITE

public mixed SCOPE_ACTIVITYPUB_WRITE = 'write:activitypub'

SCOPE_ADMIN

public mixed SCOPE_ADMIN = 'admin'

SCOPE_ADMIN_READ

public mixed SCOPE_ADMIN_READ = 'read:admin'

SCOPE_ADMIN_WRITE

public mixed SCOPE_ADMIN_WRITE = 'write:admin'

SCOPE_ISSUE

public mixed SCOPE_ISSUE = 'issue'

SCOPE_ISSUE_READ

public mixed SCOPE_ISSUE_READ = 'read:issue'

SCOPE_ISSUE_WRITE

public mixed SCOPE_ISSUE_WRITE = 'write:issue'

SCOPE_MISC

public mixed SCOPE_MISC = 'misc'

SCOPE_MISC_READ

public mixed SCOPE_MISC_READ = 'read:misc'

SCOPE_MISC_WRITE

public mixed SCOPE_MISC_WRITE = 'write:misc'

SCOPE_NOTIFICATION

public mixed SCOPE_NOTIFICATION = 'notification'

SCOPE_NOTIFICATION_READ

public mixed SCOPE_NOTIFICATION_READ = 'read:notification'

SCOPE_NOTIFICATION_WRITE

public mixed SCOPE_NOTIFICATION_WRITE = 'write:notification'

SCOPE_ORGANIZATION

public mixed SCOPE_ORGANIZATION = 'organization'

SCOPE_ORGANIZATION_READ

public mixed SCOPE_ORGANIZATION_READ = 'read:organization'

SCOPE_ORGANIZATION_WRITE

public mixed SCOPE_ORGANIZATION_WRITE = 'write:organization'

SCOPE_PACKAGE

public mixed SCOPE_PACKAGE = 'package'

SCOPE_PACKAGE_READ

public mixed SCOPE_PACKAGE_READ = 'read:package'

SCOPE_PACKAGE_WRITE

public mixed SCOPE_PACKAGE_WRITE = 'write:package'

SCOPE_REPOSITORY

public mixed SCOPE_REPOSITORY = 'repository'

SCOPE_REPOSITORY_READ

public mixed SCOPE_REPOSITORY_READ = 'read:repository'

SCOPE_REPOSITORY_WRITE

public mixed SCOPE_REPOSITORY_WRITE = 'write:repository'

SCOPE_USER

public mixed SCOPE_USER = 'user'

SCOPE_USER_READ

public mixed SCOPE_USER_READ = 'read:user'

SCOPE_USER_WRITE

public mixed SCOPE_USER_WRITE = 'write:user'

Properties

$accessTokenURL

protected string $accessTokenURL = 'https://codeberg.org/login/oauth/access_token'

$apiDocs

protected string|null $apiDocs = 'https://codeberg.org/api/swagger'

$apiURL

protected string $apiURL = 'https://codeberg.org/api'

$applicationURL

protected string|null $applicationURL = 'https://codeberg.org/user/settings/applications'

$authorizationURL

protected string $authorizationURL = 'https://codeberg.org/login/oauth/authorize'

$clientCredentialsTokenURL

An optional client credentials token endpoint in case the provider supports ClientCredentials.

protected string|null $clientCredentialsTokenURL = null

If the provider supports client credentials and $clientCredentialsTokenURL is null, $accessTokenURL will be used instead.

Tags
see
ClientCredentials::getClientCredentialsToken()

$http

The PSR-18 HTTP client

protected ClientInterface $http

$name

The name of the provider/class

protected string $name = ''

$refreshTokenURL

An optional refresh token endpoint in case the provider supports TokenRefresh.

protected string|null $refreshTokenURL = null

If the provider supports token refresh and $refreshTokenURL is null, $accessTokenURL will be used instead.

Tags
see
TokenRefresh::refreshAccessToken()

$requestFactory

A PSR-17 request factory

protected RequestFactoryInterface $requestFactory

$streamFactory

A PSR-17 stream factory

protected StreamFactoryInterface $streamFactory

$uriFactory

A PSR-17 URI factory

protected UriFactoryInterface $uriFactory

$userRevokeURL

protected string|null $userRevokeURL = 'https://codeberg.org/user/settings/applications'

Methods

__construct()

OAuthProvider constructor.

public final __construct(OAuthOptions|SettingsContainerInterface $options, ClientInterface $http, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, UriFactoryInterface $uriFactory[, OAuthStorageInterface $storage = new MemoryStorage() ][, LoggerInterface $logger = new NullLogger() ]) : mixed
Parameters
$options : OAuthOptions|SettingsContainerInterface
$http : ClientInterface
$requestFactory : RequestFactoryInterface
$streamFactory : StreamFactoryInterface
$uriFactory : UriFactoryInterface
$storage : OAuthStorageInterface = new MemoryStorage()
$logger : LoggerInterface = new NullLogger()

generateChallenge()

implements PKCE::generateChallenge()

public final generateChallenge(string $verifier, string $challengeMethod) : string
Parameters
$verifier : string
$challengeMethod : string
Tags
see
PKCE::generateChallenge()
see
OAuth2Provider::setCodeChallenge()
Return values
string

generateVerifier()

implements PKCE::generateVerifier()

public final generateVerifier(int $length) : string
Parameters
$length : int
Tags
see
PKCE::generateVerifier()
see
OAuth2Provider::setCodeChallenge()
Return values
string

getAccessToken()

Obtains an OAuth2 access token with the given $code, verifies the $state if the provider implements the CSRFToken interface, and returns an AccessToken object

public getAccessToken(string $code[, string|null $state = null ]) : AccessToken
Parameters
$code : string
$state : string|null = null
Return values
AccessToken

getAccessTokenFromStorage()

Gets an access token from the current OAuthStorageInterface (shorthand/convenience)

public final getAccessTokenFromStorage() : AccessToken
Tags
codeCoverageIgnore
Return values
AccessToken

getApiDocURL()

Returns the link to the provider's API docs, or null if the value is not set

public final getApiDocURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

getApplicationURL()

Returns the link to the provider's credential registration/application page, or null if the value is not set

public final getApplicationURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

getAuthorizationURL()

Prepares the URL with optional $params which redirects to the provider's authorization prompt and returns a PSR-7 UriInterface with all necessary parameters set.

public getAuthorizationURL([array<string, scalar>|null $params = null ][, array<string|int, string>|null $scopes = null ]) : UriInterface
Parameters
$params : array<string, scalar>|null = null
$scopes : array<string|int, string>|null = null
Return values
UriInterface

getName()

Returns the name of the provider/class

public final getName() : string
Tags
codeCoverageIgnore
Return values
string

getRequestAuthorization()

Authorizes the $request with the credentials from the given $token and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set

public getRequestAuthorization(RequestInterface $request[, AccessToken|null $token = null ]) : RequestInterface
Parameters
$request : RequestInterface
$token : AccessToken|null = null
Return values
RequestInterface

getUserRevokeURL()

Returns the link to the page where a user can revoke access tokens, or null if the value is not set

public final getUserRevokeURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

request()

Prepares an API request to $path with the given parameters, gets authorization, fires the request and returns a PSR-7 ResponseInterface with the corresponding API response

public request(string $path[, array<string|int, mixed>|null $params = null ][, string|null $method = null ][, StreamInterface|array<string|int, mixed>|string|null $body = null ][, array<string|int, mixed>|null $headers = null ][, string|null $protocolVersion = null ]) : ResponseInterface
Parameters
$path : string
$params : array<string|int, mixed>|null = null
$method : string|null = null
$body : StreamInterface|array<string|int, mixed>|string|null = null
$headers : array<string|int, mixed>|null = null
$protocolVersion : string|null = null
Tags
throws
UnauthorizedAccessException
Return values
ResponseInterface

sendRequest()

public final sendRequest(RequestInterface $request) : ResponseInterface
Parameters
$request : RequestInterface
Tags
throws
InvalidAccessTokenException
Return values
ResponseInterface

setLogger()

Sets an optional PSR-3 LoggerInterface

public final setLogger(LoggerInterface $logger) : static
Parameters
$logger : LoggerInterface
Tags
codeCoverageIgnore
Return values
static

setRequestFactory()

Sets an optional PSR-17 RequestFactoryInterface

public final setRequestFactory(RequestFactoryInterface $requestFactory) : static
Parameters
$requestFactory : RequestFactoryInterface
Tags
codeCoverageIgnore
Return values
static

setStreamFactory()

Sets an optional PSR-17 StreamFactoryInterface

public final setStreamFactory(StreamFactoryInterface $streamFactory) : static
Parameters
$streamFactory : StreamFactoryInterface
Tags
codeCoverageIgnore
Return values
static

setUriFactory()

Sets an optional PSR-17 UriFactoryInterface

public final setUriFactory(UriFactoryInterface $uriFactory) : static
Parameters
$uriFactory : UriFactoryInterface
Tags
codeCoverageIgnore
Return values
static

storeAccessToken()

Sets an access token in the current OAuthStorageInterface (shorthand/convenience)

public final storeAccessToken(AccessToken $token) : static
Parameters
$token : AccessToken
Tags
codeCoverageIgnore
Return values
static

addBasicAuthHeader()

Adds an "Authorization: Basic <base64(key:secret)>" header to the given request

protected addBasicAuthHeader(RequestInterface $request) : RequestInterface
Parameters
$request : RequestInterface
Return values
RequestInterface

cleanBodyParams()

Cleans an array of body parameters

protected cleanBodyParams(array<string, scalar|bool|null> $params) : array<string, string>
Parameters
$params : array<string, scalar|bool|null>
Return values
array<string, string>

cleanQueryParams()

Cleans an array of query parameters

protected cleanQueryParams(array<string, scalar|bool|null> $params) : array<string, string>
Parameters
$params : array<string, scalar|bool|null>
Return values
array<string, string>

construct()

A replacement constructor that you can call in extended classes, so that you don't have to implement the monstrous original `__construct()`

protected construct() : void

createAccessToken()

Creates an access token with the provider set to $this->name

protected final createAccessToken() : AccessToken
Tags
codeCoverageIgnore
Return values
AccessToken

getAccessTokenRequestBodyParams()

prepares the request body parameters for the access token request

protected getAccessTokenRequestBodyParams(string $code) : array<string, string>
Parameters
$code : string
Tags
see
OAuth2Provider::getAccessToken()
Return values
array<string, string>

getAuthorizationURLRequestParams()

prepares the query parameters for the auth URL

protected getAuthorizationURLRequestParams(array<string, scalar> $params, array<string|int, string> $scopes) : array<string, string>
Parameters
$params : array<string, scalar>
$scopes : array<string|int, string>
Tags
see
OAuth2Provider::getAuthorizationURL()
Return values
array<string, string>

getMeResponseData()

fetches the provider's "me" endpoint and returns the JSON data as an array

protected final getMeResponseData(string $endpoint[, array<string, scalar|bool|null>|null $params = null ]) : array<int|string, mixed>
Parameters
$endpoint : string
$params : array<string, scalar|bool|null>|null = null
Tags
see
UserInfo::me()
see
OAuthProvider::sendMeRequest()
see
OAuthProvider::handleMeResponseError()
throws
ProviderException
Return values
array<int|string, mixed>

getRefreshAccessTokenRequestBodyParams()

prepares the request body parameters for the token refresh

protected getRefreshAccessTokenRequestBodyParams(string $refreshToken) : array<string, string|null>
Parameters
$refreshToken : string
Tags
see
OAuth2Provider::refreshAccessToken()
Return values
array<string, string|null>

getRequestHeaders()

Prepare request headers

protected final getRequestHeaders([array<string, string>|null $headers = null ]) : array<string, string>
Parameters
$headers : array<string, string>|null = null
Return values
array<string, string>

getRequestTarget()

Determine the request target from the given URI (path segment or URL) with respect to $apiURL, anything except host and path will be ignored, scheme will always be set to "https".

protected getRequestTarget(string $uri) : string

Throws if the host of a given URL does not match the host of $apiURL.

Parameters
$uri : string
Tags
see
OAuthInterface::request()
throws
ProviderException
Return values
string

getRequestURL()

Prepares the request URL

protected final getRequestURL(string $path[, array<string, scalar|bool|null>|null $params = null ]) : string
Parameters
$path : string
$params : array<string, scalar|bool|null>|null = null
Return values
string

getTokenResponseData()

extracts the data from the access token response and returns an array with the key->value pairs contained

protected getTokenResponseData(ResponseInterface $response) : array<string, string|mixed>

we don't bother checking the content type here as it's sometimes vendor specific, not set or plain wrong: the spec mandates a JSON body which is what almost all providers send - weird exceptions:

  • mixcloud sends JSON with a "text/javascript" header
  • deezer sends form-data with a "text/html" header (???)
  • silly amazon sends gzip compressed data... (handled by decodeJSON)
Parameters
$response : ResponseInterface
Tags
see
OAuth2Provider::parseTokenResponse()
throws
JsonException
Return values
array<string, string|mixed>

handleMeResponseError()

handles errors for the `me()` endpoints - one horrible block of code to catch them all

protected final handleMeResponseError(ResponseInterface $response) : void

we could simply throw a ProviderException and be done with it, but we're nice and try to provide a message too

Parameters
$response : ResponseInterface
Tags
throws
ProviderException|UnauthorizedAccessException

parseTokenResponse()

Parses the response from a request to the token endpoint

protected parseTokenResponse(ResponseInterface $response) : AccessToken
Parameters
$response : ResponseInterface
Tags
link
https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4
link
https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
see
OAuth2Provider::getAccessToken()
see
OAuth2Provider::refreshAccessToken()
see
OAuth2Provider::getClientCredentialsToken()
throws
ProviderException
Return values
AccessToken

sendAccessTokenRequest()

sends a request to the access/refresh token endpoint $url with the given $body as form data

protected sendAccessTokenRequest(string $url, array<string, scalar|bool|null> $body) : ResponseInterface
Parameters
$url : string
$body : array<string, scalar|bool|null>
Tags
see
OAuth2Provider::getAccessToken()
see
OAuth2Provider::refreshAccessToken()
see
OAuth2Provider::getParRequestUri()
Return values
ResponseInterface

sendMeRequest()

prepares and sends the request to the provider's "me" endpoint and returns a ResponseInterface

protected sendMeRequest(string $endpoint[, array<string, scalar|bool|null>|null $params = null ]) : ResponseInterface
Parameters
$endpoint : string
$params : array<string, scalar|bool|null>|null = null
Return values
ResponseInterface

setRequestBody()

Prepares the request body and sets it in the given RequestInterface, along with a Content-Length header

protected final setRequestBody(StreamInterface|array<string, scalar|bool|null>|string $body, RequestInterface $request) : RequestInterface
Parameters
$body : StreamInterface|array<string, scalar|bool|null>|string
$request : RequestInterface
Tags
throws
ProviderException
Return values
RequestInterface

        
On this page

Search results