com.nimbusds.jwt.JWTClaimsSet Maven / Gradle / Ivy
/*
* nimbus-jose-jwt
*
* Copyright 2012-2016, Connect2id Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use
* this file except in compliance with the License. You may obtain a copy of the
* License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed
* under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
* CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*/
package com.nimbusds.jwt;
import java.io.Serializable;
import java.net.URI;
import java.net.URISyntaxException;
import java.text.ParseException;
import java.util.*;
import net.jcip.annotations.Immutable;
import com.nimbusds.jose.Payload;
import com.nimbusds.jwt.util.DateUtils;
import com.nimbusds.jose.util.JSONArrayUtils;
import com.nimbusds.jose.util.JSONObjectUtils;
/**
* JSON Web Token (JWT) claims set. This class is immutable.
*
* Supports all {@link #getRegisteredNames()} registered claims} of the JWT
* specification:
*
*
* - iss - Issuer
*
- sub - Subject
*
- aud - Audience
*
- exp - Expiration Time
*
- nbf - Not Before
*
- iat - Issued At
*
- jti - JWT ID
*
*
* The set may also contain custom claims; these will be serialised and
* parsed along the registered ones.
*
*
Example JWT claims set:
*
*
* {
* "sub" : "joe",
* "exp" : 1300819380,
* "http://example.com/is_root" : true
* }
*
*
* Example usage:
*
*
* JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
* .subject("joe")
* .expirationTime(new Date(1300819380 * 1000l)
* .claim("http://example.com/is_root", true)
* .build();
*
*
* @author Vladimir Dzhuvinov
* @author Justin Richer
* @version 2021-02-22
*/
@Immutable
public final class JWTClaimsSet implements Serializable {
private static final long serialVersionUID = 1L;
private static final String ISSUER_CLAIM = "iss";
private static final String SUBJECT_CLAIM = "sub";
private static final String AUDIENCE_CLAIM = "aud";
private static final String EXPIRATION_TIME_CLAIM = "exp";
private static final String NOT_BEFORE_CLAIM = "nbf";
private static final String ISSUED_AT_CLAIM = "iat";
private static final String JWT_ID_CLAIM = "jti";
/**
* The registered claim names.
*/
private static final Set REGISTERED_CLAIM_NAMES;
/*
* Initialises the registered claim name set.
*/
static {
Set n = new HashSet<>();
n.add(ISSUER_CLAIM);
n.add(SUBJECT_CLAIM);
n.add(AUDIENCE_CLAIM);
n.add(EXPIRATION_TIME_CLAIM);
n.add(NOT_BEFORE_CLAIM);
n.add(ISSUED_AT_CLAIM);
n.add(JWT_ID_CLAIM);
REGISTERED_CLAIM_NAMES = Collections.unmodifiableSet(n);
}
/**
* Builder for constructing JSON Web Token (JWT) claims sets.
*
* Example usage:
*
*
* JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
* .subject("joe")
* .expirationDate(new Date(1300819380 * 1000l)
* .claim("http://example.com/is_root", true)
* .build();
*
*/
public static class Builder {
/**
* The claims.
*/
private final Map claims = new LinkedHashMap<>();
/**
* Creates a new builder.
*/
public Builder() {
// Nothing to do
}
/**
* Creates a new builder with the claims from the specified
* set.
*
* @param jwtClaimsSet The JWT claims set to use. Must not be
* {@code null}.
*/
public Builder(final JWTClaimsSet jwtClaimsSet) {
claims.putAll(jwtClaimsSet.claims);
}
/**
* Sets the issuer ({@code iss}) claim.
*
* @param iss The issuer claim, {@code null} if not specified.
*
* @return This builder.
*/
public Builder issuer(final String iss) {
claims.put(ISSUER_CLAIM, iss);
return this;
}
/**
* Sets the subject ({@code sub}) claim.
*
* @param sub The subject claim, {@code null} if not specified.
*
* @return This builder.
*/
public Builder subject(final String sub) {
claims.put(SUBJECT_CLAIM, sub);
return this;
}
/**
* Sets the audience ({@code aud}) claim.
*
* @param aud The audience claim, {@code null} if not
* specified.
*
* @return This builder.
*/
public Builder audience(final List aud) {
claims.put(AUDIENCE_CLAIM, aud);
return this;
}
/**
* Sets a single-valued audience ({@code aud}) claim.
*
* @param aud The audience claim, {@code null} if not
* specified.
*
* @return This builder.
*/
public Builder audience(final String aud) {
if (aud == null) {
claims.put(AUDIENCE_CLAIM, null);
} else {
claims.put(AUDIENCE_CLAIM, Collections.singletonList(aud));
}
return this;
}
/**
* Sets the expiration time ({@code exp}) claim.
*
* @param exp The expiration time, {@code null} if not
* specified.
*
* @return This builder.
*/
public Builder expirationTime(final Date exp) {
claims.put(EXPIRATION_TIME_CLAIM, exp);
return this;
}
/**
* Sets the not-before ({@code nbf}) claim.
*
* @param nbf The not-before claim, {@code null} if not
* specified.
*
* @return This builder.
*/
public Builder notBeforeTime(final Date nbf) {
claims.put(NOT_BEFORE_CLAIM, nbf);
return this;
}
/**
* Sets the issued-at ({@code iat}) claim.
*
* @param iat The issued-at claim, {@code null} if not
* specified.
*
* @return This builder.
*/
public Builder issueTime(final Date iat) {
claims.put(ISSUED_AT_CLAIM, iat);
return this;
}
/**
* Sets the JWT ID ({@code jti}) claim.
*
* @param jti The JWT ID claim, {@code null} if not specified.
*
* @return This builder.
*/
public Builder jwtID(final String jti) {
claims.put(JWT_ID_CLAIM, jti);
return this;
}
/**
* Sets the specified claim (registered or custom).
*
* @param name The name of the claim to set. Must not be
* {@code null}.
* @param value The value of the claim to set, {@code null} if
* not specified. Should map to a JSON entity.
*
* @return This builder.
*/
public Builder claim(final String name, final Object value) {
claims.put(name, value);
return this;
}
/**
* Gets the claims (registered and custom).
*
* Note that the registered claims Expiration-Time
* ({@code exp}), Not-Before-Time ({@code nbf}) and Issued-At
* ({@code iat}) will be returned as {@code java.util.Date}
* instances.
*
* @return The claims, as an unmodifiable map, empty map if
* none.
*/
public Map getClaims() {
return Collections.unmodifiableMap(claims);
}
/**
* Builds a new JWT claims set.
*
* @return The JWT claims set.
*/
public JWTClaimsSet build() {
return new JWTClaimsSet(claims);
}
}
/**
* The claims map.
*/
private final Map claims = new LinkedHashMap<>();
/**
* Creates a new JWT claims set.
*
* @param claims The JWT claims set as a map. Must not be {@code null}.
*/
private JWTClaimsSet(final Map claims) {
this.claims.putAll(claims);
}
/**
* Gets the registered JWT claim names.
*
* @return The registered claim names, as a unmodifiable set.
*/
public static Set getRegisteredNames() {
return REGISTERED_CLAIM_NAMES;
}
/**
* Gets the issuer ({@code iss}) claim.
*
* @return The issuer claim, {@code null} if not specified.
*/
public String getIssuer() {
try {
return getStringClaim(ISSUER_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the subject ({@code sub}) claim.
*
* @return The subject claim, {@code null} if not specified.
*/
public String getSubject() {
try {
return getStringClaim(SUBJECT_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the audience ({@code aud}) claim.
*
* @return The audience claim, empty list if not specified.
*/
public List getAudience() {
Object audValue = getClaim(AUDIENCE_CLAIM);
if (audValue instanceof String) {
// Special case
return Collections.singletonList((String)audValue);
}
List aud;
try {
aud = getStringListClaim(AUDIENCE_CLAIM);
} catch (ParseException e) {
return Collections.emptyList();
}
return aud != null ? aud : Collections.emptyList();
}
/**
* Gets the expiration time ({@code exp}) claim.
*
* @return The expiration time, {@code null} if not specified.
*/
public Date getExpirationTime() {
try {
return getDateClaim(EXPIRATION_TIME_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the not-before ({@code nbf}) claim.
*
* @return The not-before claim, {@code null} if not specified.
*/
public Date getNotBeforeTime() {
try {
return getDateClaim(NOT_BEFORE_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the issued-at ({@code iat}) claim.
*
* @return The issued-at claim, {@code null} if not specified.
*/
public Date getIssueTime() {
try {
return getDateClaim(ISSUED_AT_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the JWT ID ({@code jti}) claim.
*
* @return The JWT ID claim, {@code null} if not specified.
*/
public String getJWTID() {
try {
return getStringClaim(JWT_ID_CLAIM);
} catch (ParseException e) {
return null;
}
}
/**
* Gets the specified claim (registered or custom).
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*/
public Object getClaim(final String name) {
return claims.get(name);
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.String}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public String getStringClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null || value instanceof String) {
return (String)value;
} else {
throw new ParseException("The \"" + name + "\" claim is not a String", 0);
}
}
/**
* Gets the specified claims (registered or custom) as a
* {@link java.lang.String} array.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public String[] getStringArrayClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
}
List list;
try {
list = (List)getClaim(name);
} catch (ClassCastException e) {
throw new ParseException("The \"" + name + "\" claim is not a list / JSON array", 0);
}
String[] stringArray = new String[list.size()];
for (int i=0; i < stringArray.length; i++) {
try {
stringArray[i] = (String)list.get(i);
} catch (ClassCastException e) {
throw new ParseException("The \"" + name + "\" claim is not a list / JSON array of strings", 0);
}
}
return stringArray;
}
/**
* Gets the specified claims (registered or custom) as a
* {@link java.util.List} list of strings.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public List getStringListClaim(final String name)
throws ParseException {
String[] stringArray = getStringArrayClaim(name);
if (stringArray == null) {
return null;
}
return Collections.unmodifiableList(Arrays.asList(stringArray));
}
/**
* Gets the specified claim (registered or custom) as a
* {@link java.net.URI}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim couldn't be parsed to a URI.
*/
public URI getURIClaim(final String name)
throws ParseException {
String uriString = getStringClaim(name);
if (uriString == null) {
return null;
}
try {
return new URI(uriString);
} catch (URISyntaxException e) {
throw new ParseException("The \"" + name + "\" claim is not a URI: " + e.getMessage(), 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.Boolean}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Boolean getBooleanClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null || value instanceof Boolean) {
return (Boolean)value;
} else {
throw new ParseException("The \"" + name + "\" claim is not a Boolean", 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.Integer}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Integer getIntegerClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Number) {
return ((Number)value).intValue();
} else {
throw new ParseException("The \"" + name + "\" claim is not an Integer", 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.Long}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Long getLongClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Number) {
return ((Number)value).longValue();
} else {
throw new ParseException("The \"" + name + "\" claim is not a Number", 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.util.Date}. The claim may be represented by a Date
* object or a number of a seconds since the Unix epoch.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Date getDateClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Date) {
return (Date)value;
} else if (value instanceof Number) {
return DateUtils.fromSecondsSinceEpoch(((Number)value).longValue());
} else {
throw new ParseException("The \"" + name + "\" claim is not a Date", 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.Float}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Float getFloatClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Number) {
return ((Number)value).floatValue();
} else {
throw new ParseException("The \"" + name + "\" claim is not a Float", 0);
}
}
/**
* Gets the specified claim (registered or custom) as
* {@link java.lang.Double}.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Double getDoubleClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Number) {
return ((Number)value).doubleValue();
} else {
throw new ParseException("The \"" + name + "\" claim is not a Double", 0);
}
}
/**
* Gets the specified claim (registered or custom) as a JSON object.
*
* @param name The name of the claim. Must not be {@code null}.
*
* @return The value of the claim, {@code null} if not specified.
*
* @throws ParseException If the claim value is not of the required
* type.
*/
public Map getJSONObjectClaim(final String name)
throws ParseException {
Object value = getClaim(name);
if (value == null) {
return null;
} else if (value instanceof Map) {
Map jsonObject = JSONObjectUtils.newJSONObject();
Map map = (Map)value;
for (Map.Entry entry: map.entrySet()) {
if (entry.getKey() instanceof String) {
jsonObject.put((String)entry.getKey(), entry.getValue());
}
}
return jsonObject;
} else {
throw new ParseException("The \"" + name + "\" claim is not a JSON object or Map", 0);
}
}
/**
* Gets the claims (registered and custom).
*
* Note that the registered claims Expiration-Time ({@code exp}),
* Not-Before-Time ({@code nbf}) and Issued-At ({@code iat}) will be
* returned as {@code java.util.Date} instances.
*
* @return The claims, as an unmodifiable map, empty map if none.
*/
public Map getClaims() {
return Collections.unmodifiableMap(claims);
}
/**
* Returns a JOSE object payload representation of this claims set.
*
* @return The payload representation.
*/
public Payload toPayload() {
return new Payload(toJSONObject());
}
/**
* Returns the JSON object representation of this claims set. The
* claims are serialised according to their insertion order. Claims
* with {@code null} values are not output.
*
* @return The JSON object representation.
*/
public Map toJSONObject() {
return toJSONObject(false);
}
/**
* Returns the JSON object representation of this claims set. The
* claims are serialised according to their insertion order.
*
* @param includeClaimsWithNullValues If {@code true} claims with
* {@code null} values will also be
* output.
*
* @return The JSON object representation.
*/
public Map toJSONObject(final boolean includeClaimsWithNullValues) {
Map o = JSONObjectUtils.newJSONObject();
for (Map.Entry claim: claims.entrySet()) {
if (claim.getValue() instanceof Date) {
// Transform dates to Unix timestamps
Date dateValue = (Date) claim.getValue();
o.put(claim.getKey(), DateUtils.toSecondsSinceEpoch(dateValue));
} else if (AUDIENCE_CLAIM.equals(claim.getKey())) {
// Serialise single audience list and string
List audList = getAudience();
if (audList != null && ! audList.isEmpty()) {
if (audList.size() == 1) {
o.put(AUDIENCE_CLAIM, audList.get(0));
} else {
List