Authorization
Enum Authorization.
Description
Represents supported HTTP Authorization header authentication schemes and
provides helpers to parse raw header values into structured credential
objects.
The Authorization header is used to authenticate a user agent with a
server, as defined primarily in RFC 7235 and scheme-specific RFCs. This
utility enum MUST be used in a case-sensitive manner for its enum values
but MUST treat incoming header names and schemes according to the
specification of each scheme. Callers SHOULD use the parsing helpers to
centralize and normalize authentication handling.
Cases
A common, non-standard scheme for API key authentication.
Amazon Web Services Signature Version 4 scheme.
Basic authentication scheme using Base64-encoded "username:password".
Bearer token authentication scheme.
Digest access authentication scheme.
Methods
Extracts and parses the Authorization header from a collection of headers.
Extracts and parses the Authorization header from a PSR-7 request.
Parses a raw Authorization header string into a structured credential object.
Parses credentials for the ApiKey authentication scheme.
Parses credentials for the AWS Signature Version 4 authentication scheme.
Parses credentials for the Basic authentication scheme.
Parses credentials for the Bearer authentication scheme.
Parses credentials for the Digest authentication scheme.
A common, non-standard scheme for API key authentication.
Description
This scheme is not defined by an RFC and MAY vary between APIs. Implementations using this scheme SHOULD document how the key is generated, scoped, and validated.
Basic authentication scheme using Base64-encoded "username:password".
Description
Credentials are transmitted in plaintext (after Base64 decoding) and therefore MUST only be used over secure transports such as HTTPS.
Bearer token authentication scheme.
Description
Commonly used with OAuth 2.0 access tokens and JWTs. Bearer tokens MUST be treated as opaque secrets; any party in possession of a valid token MAY use it to obtain access.
Digest access authentication scheme.
Description
Uses a challenge-response mechanism to avoid sending passwords in cleartext. Implementations SHOULD fully follow the RFC requirements to avoid interoperability and security issues.
Amazon Web Services Signature Version 4 scheme.
Description
Used to authenticate requests to AWS services. The credential components MUST be constructed according to the AWS Signature Version 4 process, or validation will fail on the server side.
Extracts and parses the Authorization header from a collection of headers.
public
static
fromHeaderCollection(
array<string|int, mixed>
$headers) : AuthorizationCredential|null
Description
This method MUST treat header names case-insensitively and SHALL use
the first Authorization value if multiple values are provided. If the
header is missing or cannot be parsed successfully, it MUST return null.
Parameters
$headers
:
array<string|int, mixed>
Description
an associative array of HTTP headers
Return values
Description
a parsed credential object or null if not present or invalid
Extracts and parses the Authorization header from a PSR-7 request.
public
static
fromRequest(RequestInterface
$request) : AuthorizationCredential|null
Description
This method SHALL delegate to Authorization::fromHeaderCollection() using the request's header collection. It MUST NOT modify the request.
Parameters
$request
:
RequestInterface
Description
the PSR-7 request instance
Return values
Description
a parsed credential object or null if not present or invalid
Parses a raw Authorization header string into a structured credential object.
public
static
parse(
string
$header) : AuthorizationCredential|null
Description
This method MUST:
- Split the header into an authentication scheme and a credentials part.
- Resolve the scheme to a supported enum value.
- Delegate to the appropriate scheme-specific parser. If the header is empty, malformed, or uses an unsupported scheme, this method MUST return null. Callers SHOULD treat a null result as an authentication parsing failure.
Parameters
$header
:
string
Description
the raw value of the Authorization header
Return values
Description
a credential object on successful parsing, or null on failure
Parses credentials for the ApiKey authentication scheme.
private
static
parseApiKey(
string
$credentials) : ApiKeyCredential
Description
The complete credential string MUST be treated as the API key. No additional structure is assumed or validated here; callers MAY apply further validation according to application rules.
Parameters
$credentials
:
string
Description
the raw credentials portion of the header
Return values
Description
the parsed API key credential object
Parses credentials for the AWS Signature Version 4 authentication scheme.
private
static
parseAws(
string
$credentials) : AwsCredential|null
Description
This method MUST parse comma-separated key=value pairs and verify that
the mandatory parameters Credential, SignedHeaders, and Signature
are present. The Signature value MUST be a 64-character hexadecimal
string. If parsing or validation fails, it MUST return null.
The Credential parameter contains the full credential scope in the form
AccessKeyId/Date/Region/Service/aws4_request, which SHALL be stored
as-is for downstream processing.
Parameters
$credentials
:
string
Description
the raw credentials portion of the header
Return values
Description
the parsed AWS credential object, or null on failure
Parses credentials for the Basic authentication scheme.
private
static
parseBasic(
string
$credentials) : BasicCredential|null
Description
This method MUST:
- Base64-decode the credentials.
- Split the decoded string into
username:password. If decoding fails or the decoded value does not contain exactly one colon separator, this method MUST return null.
Parameters
$credentials
:
string
Description
the Base64-encoded "username:password" string
Return values
Description
the parsed Basic credential, or null on failure
Parses credentials for the Bearer authentication scheme.
private
static
parseBearer(
string
$credentials) : BearerCredential
Description
The credentials MUST be treated as an opaque bearer token. This method SHALL NOT attempt to validate or inspect the token contents.
Parameters
$credentials
:
string
Description
the bearer token string
Return values
Description
the parsed Bearer credential object
Parses credentials for the Digest authentication scheme.
private
static
parseDigest(
string
$credentials) : DigestCredential|null
Description
This method MUST parse comma-separated key=value pairs according to RFC 7616. Values MAY be quoted or unquoted. If any part is malformed or required parameters are missing, it MUST return null. Required parameters:
- username
- realm
- nonce
- uri
- response
- qop
- nc
- cnonce
Optional parameters such as
opaqueandalgorithmSHALL be included in the credential object when present.
Parameters
$credentials
:
string
Description
the raw credentials portion of the header
Return values
Description
the parsed Digest credential object, or null on failure