001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.saml; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.Immutable; 023import java.util.Optional; 024 025/** 026 * A validated NameID with its identity-significant qualifiers. The value alone is not a stable 027 * cross-tenant account key. Transient and unspecified formats never yield a {@link SamlSubjectKey}. 028 * 029 * @since 1.0.0 030 */ 031@Immutable 032public final class SamlNameId { 033 static final String PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"; 034 static final String TRANSIENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"; 035 036 private final @NonNull String value; 037 private final @Nullable String format; 038 private final @Nullable String nameQualifier; 039 private final @Nullable String spNameQualifier; 040 private final @Nullable String spProvidedId; 041 042 SamlNameId(@NonNull String value, @Nullable String format, @Nullable String nameQualifier, 043 @Nullable String spNameQualifier) { 044 this(value, format, nameQualifier, spNameQualifier, null); 045 } 046 047 SamlNameId(@NonNull String value, @Nullable String format, @Nullable String nameQualifier, 048 @Nullable String spNameQualifier, @Nullable String spProvidedId) { 049 this.value = value; 050 this.format = format; 051 this.nameQualifier = nameQualifier; 052 this.spNameQualifier = spNameQualifier; 053 this.spProvidedId = spProvidedId; 054 } 055 056 /** 057 * Returns the validated NameID text. 058 * 059 * @return value 060 * @since 1.0.0 061 */ 062 public @NonNull String getValue() { return value; } 063 /** 064 * Returns the format URI when present. 065 * 066 * @return optional format 067 * @since 1.0.0 068 */ 069 public @NonNull Optional<@NonNull String> getFormat() { return Optional.ofNullable(format); } 070 /** 071 * Returns the NameQualifier when present. 072 * 073 * @return optional qualifier 074 * @since 1.0.0 075 */ 076 public @NonNull Optional<@NonNull String> getNameQualifier() { return Optional.ofNullable(nameQualifier); } 077 /** 078 * Returns the SPNameQualifier when present. 079 * 080 * @return optional qualifier 081 * @since 1.0.0 082 */ 083 public @NonNull Optional<@NonNull String> getSpNameQualifier() { return Optional.ofNullable(spNameQualifier); } 084 /** 085 * Returns the SPProvidedID when the IdP supplied one. This attribute is retained for 086 * exact NameID matching and outbound Single Logout. 087 * 088 * @return optional SPProvidedID 089 * @since 1.0.0 090 */ 091 public @NonNull Optional<@NonNull String> getSpProvidedId() { return Optional.ofNullable(spProvidedId); } 092 /** 093 * Reports whether the format explicitly marks this identifier transient. 094 * 095 * @return true for transient 096 * @since 1.0.0 097 */ 098 public @NonNull Boolean isTransient() { return TRANSIENT.equals(format); } 099 /** 100 * Redacts the subject. 101 * 102 * @return redacted description 103 * @since 1.0.0 104 */ 105 @Override public @NonNull String toString() { return "SamlNameId{<redacted>}"; } 106 107 boolean persistent() { return PERSISTENT.equals(format); } 108 @Nullable String rawFormat() { return format; } 109 @Nullable String rawNameQualifier() { return nameQualifier; } 110 @Nullable String rawSpNameQualifier() { return spNameQualifier; } 111 @Nullable String rawSpProvidedId() { return spProvidedId; } 112}