OAuth2 is a protocol that lets external applications request authentication of the user and authorization to perform actions using the web service on their behalf without getting their password. It is an alternative to HTTP Digest Access Authentication that MusicBrainz currently uses.
- 1 Basic steps
- 2 Authorization
- 3 Scopes
- 4 Access token usage
Registering an application
All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client I and Client Secret. The OAuth protocol recognizes two types of applications:
- Confidential - Applications that can keep secrets. Typically web applications, running on a server.
- Public - Applications that have their code exposed to the public and therefore cannot keep secrets. There are typically installed desktop applications or web applications running in the browser.
Client Secret assigned to Confidential applications should not be shared. This does not apply to Public applications, in which case the assigned Client Secret is not treated as a secret and can be embedded in the application code.
Obtaining access token
Using access token
After an application has obtained an access token, it may use the token in the web service to get user details or submit data to MusicBrainz on the user's behalf. There are two types of access tokens:
- Bearer - Very easy to use, but can be used only over HTTPS.
- MAC - Requires requests to be signed with a secret, but can be used over both HTTP and HTTPS.
Refreshing access token
Access tokens have a limited life-time. During the authorization process, application receives a refresh token, in addition to the first access token. This refresh token allows applications to obtain new access tokens.
The authorization sequence starts by redirecting the user to the authorization endpoint with a set of query string parameters describing the authorization request. The endpoint is located at
https://musicbrainz.org/oauth2/authorize and is only accessible over HTTPS. HTTP connections are refused.
The following set of query string parameters is supported by the MusicBrainz authentication endpoint:
- Must be always set to
- Client ID assigned to your application. You can find it on the website in your list of registered applications.
- URL where clients should be redirected after authorization. This must match exactly the URL you entered when registering your application. Desktop applications can use either
http://localhostwith a custom port.
- Space delimited list of scopes the application requests. See below for a list of all available scopes.
- Any string the application wants passed back after authorization. For example, this can be a CSRF token from your application. This parameter is optional, but strongly recommended.
For example, a complete authorization request from a web application requesting permissions to read the user's private tags and ratings would look like this:
https://musicbrainz.org/oauth2/authorize? response_type=code& client_id=uTuPnUfMRQPx8HBnHf22eg& redirect_uri=http%3A%2F%2Fwww.example.com.com%2Fauth2callback& scope=tag%20rating& state=1351449443
The response to the authorization request will be sent to the URL indicated in the
redirect_uri parameter. The authorization endpoint will redirect the user to this URL with a set of specific query string parameters indicating the result. If the user does not approve the request or there is a problem with the request, it will return an error describing the problem. Otherwise it will return an authorization code that can be exchanged for an access token by the token endpoint.
In case of an error, the response will look like this:
Possible error codes are
access_denied. If there is a problem with the
redirect_uri parameters, the authorization endpoint will not redirect back to your application and only inform the user about the problem.
A successful authorization response:
Refreshing an access token
Authorization requests have a limited scope. You should request only the scopes that your application necessarily needs. The following scopes are available in the MusicBrainz OAuth implementation:
- View the user's public profile information (username, age, country, homepage).
- View the user's email.
- View and modify the user's private tags.
- View and modify the user's private ratings.
- View and modify the user's private collections.
- Submit new PUIDs to the database.
- Submit new ISRCs to the database.
- Submit barcodes to the database.
Access token usage
The authorization endpoint can return two types of access tokens. The authentication process is different for each of them.
Bearer tokens are the default type of access tokens. They are very easy to use, consist only of one component, which you should treat as a password. For this reason, it is only possible to use them over HTTPS. If you try to send them over plain HTTP, they will be ignored.
The preferred method to use bearer tokens is via the
Authorization header. An authenticated request would look like the following:
GET /ws/2/user?name=xxx HTTP/1.1 Host: musicbrainz.org Authorization: Bearer jr5xkCAg4hGcls9FXMVIuQ
If you can't use the
Authorization header, there is an alternative in which you can pass the access token in the
access_token query string parameter:
You can try it with the curl command line application:
curl -H 'Authorization: Bearer jr5xkCAg4hGcls9FXMVIuQ' https://musicbrainz.org/ws/2/user?name=xxx
Or the query string parameter version:
Bearer tokens are specified in RFC 6750.
The specification of MAC token usage is not yet complete, so this authentication method might change as the specification develops. MusicBrainz implementation is based on revision 01 of the specification draft and only supports HMAC-SHA1 signatures.
MAC tokens consist of a public access token and a secret key associated with the token. They require application developers to send signed requests and can be used over both HTTP and HTTPS, because the access token alone is not considered a secret.
First the application needs to get the current timestamp and a random string called nonce that should be unique for the timestamp. Let's assume we have timestamp
1336363200 and nonce
dj83hs9s. We need to calculate a HMAC signature of the request, which is done from a normalized request string as defined by the MAC authentication specification.
1336363200\n dj83hs9s\n GET\n /ws/2/user?name=xxx\n musicbrainz.org\n 80\n \n
Using this string as a message and the secret key assigned from the token, we calculate a base64 encoded signature using HMAC-SHA1, which in this example is
MY2RO3VylIdLgFXx8bIdyce/544= if the secret key was
An authenticated request with access token
jr5xkCAg4hGcls9FXMVIuQ would then look like the following:
GET /ws/2/user?name=xxx HTTP/1.1 Host: musicbrainz.org Authorization: MAC id="jr5xkCAg4hGcls9FXMVIuQ" ts="1336363200" nonce="dj83hs9s" mac="MY2RO3VylIdLgFXx8bIdyce/544="
If you want to use use this authentication method, please refer to the specification for details or use an OAuth 2.0 client library that has it already implemenmted.